postgresai 0.16.0-dev.0 → 0.16.0-dev.2

package/bin/postgres-ai.ts

@@ -2443,9 +2443,44 @@ interface MonitoringRegistration {
  *
  * Never throws — registration is best-effort; returns null on failure.
  */
+
+/**
+ * Classify how `mon local-install` should register the monitoring instance,
+ * given the raw `--project` value and the resolved instance id.
+ *
+ * - With an instance id: ADOPT the provisioned instance. No project name is
+ *   required (the platform returns the real project); a provided name is
+ *   normalized and carried through for messaging/fallback.
+ * - No instance id and no project name: ERROR. The hardcoded
+ *   "postgres-ai-monitoring" default was removed, and a nameless legacy
+ *   self-registration is rejected by v1.monitoring_instance_register (PT400).
+ * - No instance id but a project name: legacy SELF-REGISTER.
+ *
+ * Pure (no I/O) so the decision is unit-testable independently of the large
+ * install command. `projectName` is the trimmed value, or undefined when empty.
+ */
+type MonRegistrationPlan =
+  | { kind: "adopt"; projectName: string | undefined }
+  | { kind: "self-register"; projectName: string }
+  | { kind: "error-missing-project"; projectName: undefined };
+
+function planMonitoringRegistration(args: {
+  project?: string;
+  instanceId?: string;
+}): MonRegistrationPlan {
+  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: string,
-  projectName: string,
+  projectName: string | undefined,
   opts?: { apiBaseUrl?: string; debug?: boolean; instanceId?: string; retries?: number; retryDelayMs?: number }
 ): Promise<MonitoringRegistration | null> {
   const { apiBaseUrl } = resolveBaseUrls(opts);
@@ -2457,16 +2492,25 @@ async function registerMonitoringInstance(
   // moment to recover; skipped before the first attempt. Tests pass 0.
   const retryDelayMs = opts?.retryDelayMs ?? 400;
 
+  // Omit project_name entirely when empty: the adopt path (instance_id present)
+  // relies on the platform returning the real project, and a nameless legacy
+  // self-registration is rejected by v1.monitoring_instance_register (PT400).
+  const hasProjectName = !!(projectName && projectName.trim());
+
   if (debug) {
     console.error(`\nDebug: Registering monitoring instance...`);
     console.error(`Debug: POST ${url}`);
-    console.error(`Debug: project_name=${projectName}${instanceId ? ` instance_id=${instanceId}` : ""}`);
+    console.error(
+      `Debug: ${hasProjectName ? `project_name=${projectName}` : "project_name=(omitted)"}${instanceId ? ` instance_id=${instanceId}` : ""}`
+    );
   }
 
   const requestBody: Record<string, string> = {
     api_token: apiKey,
-    project_name: projectName,
   };
+  if (hasProjectName) {
+    requestBody.project_name = projectName as string;
+  }
   if (instanceId) {
     requestBody.instance_id = instanceId;
   }
@@ -3137,8 +3181,11 @@ mon
     // and persisted; the legacy self-registration stays fire-and-forget
     // (issue platform-all#311).
     if (apiKey && !opts.demo) {
-      const projectName = opts.project || "postgres-ai-monitoring";
       const instanceId = opts.instanceId || process.env.PGAI_INSTANCE_ID;
+      const plan = planMonitoringRegistration({ project: opts.project, instanceId });
+      const projectName = plan.projectName;
+      // `instanceId` truthy ⟺ plan.kind === "adopt"; branch on it directly so
+      // TypeScript narrows instanceId to a defined string in the adopt path.
       if (instanceId) {
         const reg = await registerMonitoringInstance(apiKey, projectName, {
           apiBaseUrl: globalOpts.apiBaseUrl,
@@ -3160,11 +3207,17 @@ mon
           // Request succeeded but carried no usable project field — don't claim
           // adoption, but don't report a hard failure either (no re-run needed).
           console.error(
-            `⚠ Adopted provisioned instance ${instanceId} but the platform returned no project — reports will use project '${projectName}'`
+            `⚠ Adopted provisioned instance ${instanceId} but the platform returned no project` +
+              (projectName
+                ? ` — reports will use project '${projectName}'`
+                : ` — reports will have no project until 'postgresai mon local-install' is re-run with --project <name>`)
           );
         } else {
           console.error(
-            `⚠ Could not adopt provisioned instance ${instanceId} — reports will use project '${projectName}' until 'postgresai mon local-install' is re-run`
+            `⚠ Could not adopt provisioned instance ${instanceId}` +
+              (projectName
+                ? ` — reports will use project '${projectName}' until 'postgresai mon local-install' is re-run`
+                : ` — reports will have no project until 'postgresai mon local-install' is re-run with --project <name>`)
           );
         }
 
@@ -3188,6 +3241,17 @@ mon
             `⚠ AAS auto-collection not registered (${aas.reason}); it can be enabled later by re-running 'postgresai mon local-install'\n`
           );
         }
+      } else if (plan.kind === "error-missing-project") {
+        // Legacy self-registration (no --instance-id) now requires a project
+        // name: the hardcoded "postgres-ai-monitoring" default was removed, and
+        // v1.monitoring_instance_register raises PT400 for a nameless legacy
+        // registration. Console-provisioned installs should adopt with
+        // --instance-id instead.
+        console.error(
+          "✗ 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 {
         void registerMonitoringInstance(apiKey, projectName, {
           apiBaseUrl: globalOpts.apiBaseUrl,
@@ -5488,3 +5552,4 @@ if (import.meta.main) {
 // same functions used by the `mon` commands).
 export { refreshBundledComposeIfStale, readDeployedTag, isValidComposeYaml };
 export { registerMonitoringInstance, resolveAdoptedProject, type MonitoringRegistration };
+export { planMonitoringRegistration, type MonRegistrationPlan };

package/dist/bin/postgres-ai.js

@@ -13425,7 +13425,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.16.0-dev.0",
+  version: "0.16.0-dev.2",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16256,7 +16256,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.16.0-dev.0";
+var version = "0.16.0-dev.2";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -28498,7 +28498,7 @@ function grafanaBaseUrl() {
   return (process.env.PGAI_GRAFANA_LOCAL_URL || "http://localhost:3000").replace(/\/+$/, "");
 }
 function grafanaAdminUser() {
-  return process.env.GF_SECURITY_ADMIN_USER || "admin";
+  return process.env.GF_SECURITY_ADMIN_USER || "monitor";
 }
 function parseVcpus(raw) {
   if (raw === undefined || raw === null || raw === "")
@@ -28575,9 +28575,14 @@ async function resolveDatasourceId(adminPassword, debug = false) {
       return null;
     const list = await res.json().catch(() => []);
     const prom = list.filter((d) => d.type === "prometheus");
-    if (prom.length !== 1) {
+    if (prom.length > 1) {
       if (debug)
-        console.error(`Debug: AAS: expected 1 prometheus datasource, found ${prom.length}`);
+        console.error(`Debug: AAS: ${prom.length} prometheus datasources (ambiguous); not retrying`);
+      return "ambiguous";
+    }
+    if (prom.length === 0) {
+      if (debug)
+        console.error(`Debug: AAS: no prometheus datasource resolvable yet`);
       return null;
     }
     return typeof prom[0].id === "number" ? prom[0].id : null;
@@ -28593,7 +28598,23 @@ async function registerAasCollection(apiKey, instanceId, opts) {
     const labels = resolveAasLabels(opts.instancesPath);
     if (!labels)
       return { ok: false, reason: "could not determine a single (cluster, node_name) target" };
-    const datasourceId = await resolveDatasourceId(opts.grafanaPassword, debug);
+    const maxAttempts = opts.datasourceMaxAttempts ?? 20;
+    const retryDelayMs = opts.datasourceRetryDelayMs ?? 3000;
+    let datasourceId = null;
+    for (let attempt = 1;attempt <= maxAttempts; attempt++) {
+      const resolved = await resolveDatasourceId(opts.grafanaPassword, debug);
+      if (typeof resolved === "number") {
+        datasourceId = resolved;
+        break;
+      }
+      if (resolved === "ambiguous")
+        break;
+      if (attempt < maxAttempts) {
+        if (debug)
+          console.error(`Debug: AAS: datasource not resolvable yet (attempt ${attempt}/${maxAttempts}); waiting for Grafana…`);
+        await new Promise((resolve4) => setTimeout(resolve4, retryDelayMs));
+      }
+    }
     if (datasourceId == null)
       return { ok: false, reason: "could not resolve the Prometheus datasource id" };
     const saToken = await mintAasServiceAccountToken(opts.grafanaPassword, debug);
@@ -35638,6 +35659,16 @@ 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`;
@@ -35645,16 +35676,19 @@ async function registerMonitoringInstance(apiKey, projectName, opts) {
   const instanceId = opts?.instanceId;
   const retries = opts?.retries ?? (instanceId ? 1 : 0);
   const retryDelayMs = opts?.retryDelayMs ?? 400;
+  const hasProjectName = !!(projectName && projectName.trim());
   if (debug) {
     console.error(`
 Debug: Registering monitoring instance...`);
     console.error(`Debug: POST ${url}`);
-    console.error(`Debug: project_name=${projectName}${instanceId ? ` instance_id=${instanceId}` : ""}`);
+    console.error(`Debug: ${hasProjectName ? `project_name=${projectName}` : "project_name=(omitted)"}${instanceId ? ` instance_id=${instanceId}` : ""}`);
   }
   const requestBody = {
-    api_token: apiKey,
-    project_name: projectName
+    api_token: apiKey
   };
+  if (hasProjectName) {
+    requestBody.project_name = projectName;
+  }
   if (instanceId) {
     requestBody.instance_id = instanceId;
   }
@@ -36197,8 +36231,9 @@ Searched: ${demoCandidates.join(", ")}
   console.log(`\u2713 Services started
 `);
   if (apiKey && !opts.demo) {
-    const projectName = opts.project || "postgres-ai-monitoring";
     const instanceId = opts.instanceId || process.env.PGAI_INSTANCE_ID;
+    const plan = planMonitoringRegistration({ project: opts.project, instanceId });
+    const projectName = plan.projectName;
     if (instanceId) {
       const reg = await registerMonitoringInstance(apiKey, projectName, {
         apiBaseUrl: globalOpts.apiBaseUrl,
@@ -36214,9 +36249,9 @@ Searched: ${demoCandidates.join(", ")}
         console.log(`\u2713 ${verb} monitoring instance (project: ${adoptedProject})
 `);
       } else if (reg) {
-        console.error(`\u26A0 Adopted provisioned instance ${instanceId} but the platform returned no project \u2014 reports will use project '${projectName}'`);
+        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} \u2014 reports will use project '${projectName}' until 'postgresai mon local-install' is re-run`);
+        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>`));
       }
       const aas = await registerAasCollection(apiKey, instanceId, {
         grafanaPassword,
@@ -36232,6 +36267,9 @@ Searched: ${demoCandidates.join(", ")}
         console.error(`\u26A0 AAS auto-collection not registered (${aas.reason}); it can be enabled later by re-running 'postgresai mon local-install'
 `);
       }
+    } else if (plan.kind === "error-missing-project") {
+      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, {
         apiBaseUrl: globalOpts.apiBaseUrl,
@@ -37997,5 +38035,6 @@ export {
   registerMonitoringInstance,
   refreshBundledComposeIfStale,
   readDeployedTag,
+  planMonitoringRegistration,
   isValidComposeYaml
 };

package/lib/aas-onboard.ts

@@ -28,7 +28,11 @@ function grafanaBaseUrl(): string {
 }
 
 function grafanaAdminUser(): string {
-  return process.env.GF_SECURITY_ADMIN_USER || "admin";
+  // The monitoring stack's compose hardcodes the Grafana admin user to
+  // "monitor" (GF_SECURITY_ADMIN_USER: monitor), so default to that rather than
+  // Grafana's stock "admin" — otherwise AAS arming logs in as the wrong user
+  // and every datasource lookup 401s. An explicit env override still wins.
+  return process.env.GF_SECURITY_ADMIN_USER || "monitor";
 }
 
 /** Parse a vcpus input (flag/env) to a non-negative integer; 0 = "unknown" fallback. */
@@ -130,17 +134,26 @@ export async function mintAasServiceAccountToken(
  * Resolve the single Prometheus-typed datasource's numeric id on the local
  * Grafana. The monitoring stack's VictoriaMetrics datasource is type
  * "prometheus" (VM speaks PromQL), and the stack registers exactly one such
- * datasource — the same one the collector queries. >1 or 0 → null (skip),
- * matching v1.aas_onboard's discovery contract.
+ * datasource — the same one the collector queries. 0 / API-not-ready → null
+ * (a provisioning transient — the readiness loop retries); >1 → "ambiguous"
+ * (a permanent misconfiguration — the loop stops at once), matching
+ * v1.aas_onboard's >1 skip.
  */
-export async function resolveDatasourceId(adminPassword: string, debug = false): Promise<number | null> {
+export async function resolveDatasourceId(adminPassword: string, debug = false): Promise<number | "ambiguous" | null> {
   try {
     const res = await grafanaApi("GET", "/api/datasources", adminPassword);
     if (!res.ok) return null;
     const list = (await res.json().catch(() => [])) as Array<{ id?: unknown; type?: unknown }>;
     const prom = list.filter((d) => d.type === "prometheus");
-    if (prom.length !== 1) {
-      if (debug) console.error(`Debug: AAS: expected 1 prometheus datasource, found ${prom.length}`);
+    if (prom.length > 1) {
+      // >1 is a permanent misconfiguration, not a provisioning transient: the
+      // datasource count only grows as Grafana provisions, so retrying can never
+      // resolve it. Signal a definitive skip so the readiness loop bails at once.
+      if (debug) console.error(`Debug: AAS: ${prom.length} prometheus datasources (ambiguous); not retrying`);
+      return "ambiguous";
+    }
+    if (prom.length === 0) {
+      if (debug) console.error(`Debug: AAS: no prometheus datasource resolvable yet`);
       return null;
     }
     return typeof prom[0].id === "number" ? prom[0].id : null;
@@ -169,6 +182,10 @@ export async function registerAasCollection(
     apiBaseUrl?: string;
     debug?: boolean;
     fetchImpl?: typeof fetch;
+    // Grafana-readiness polling for the datasource lookup (Grafana has just
+    // been started by `compose up`). Defaults: 20 attempts × 3s.
+    datasourceMaxAttempts?: number;
+    datasourceRetryDelayMs?: number;
   }
 ): Promise<AasRegisterResult> {
   const debug = !!opts.debug;
@@ -178,7 +195,24 @@ export async function registerAasCollection(
     const labels = resolveAasLabels(opts.instancesPath);
     if (!labels) return { ok: false, reason: "could not determine a single (cluster, node_name) target" };
 
-    const datasourceId = await resolveDatasourceId(opts.grafanaPassword, debug);
+    // Grafana was just started by `compose up`; it needs time to create its
+    // admin user, provision datasources, and serve its API. Querying too early
+    // makes the datasource lookup fail transiently, so poll until it resolves
+    // (best-effort, capped — the install never blocks on this).
+    const maxAttempts = opts.datasourceMaxAttempts ?? 20;
+    const retryDelayMs = opts.datasourceRetryDelayMs ?? 3000;
+    let datasourceId: number | null = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const resolved = await resolveDatasourceId(opts.grafanaPassword, debug);
+      if (typeof resolved === "number") { datasourceId = resolved; break; }
+      // "ambiguous" (>1 prometheus datasource) is permanent — retrying can't fix
+      // it, so stop polling immediately instead of waiting out the whole budget.
+      if (resolved === "ambiguous") break;
+      if (attempt < maxAttempts) {
+        if (debug) console.error(`Debug: AAS: datasource not resolvable yet (attempt ${attempt}/${maxAttempts}); waiting for Grafana…`);
+        await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+      }
+    }
     if (datasourceId == null) return { ok: false, reason: "could not resolve the Prometheus datasource id" };
 
     const saToken = await mintAasServiceAccountToken(opts.grafanaPassword, debug);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.16.0-dev.0",
+  "version": "0.16.0-dev.2",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,

package/test/aas-onboard.test.ts

@@ -198,6 +198,8 @@ describe("registerAasCollection", () => {
       installFetch({ prometheusCount: n });
       const r = await registerAasCollection("apikey-1", "inst-123", {
         grafanaPassword: "pw", instancesPath, vcpus: 8, apiBaseUrl: "https://api.test",
+        // 0/>1 is a definitive skip; cap the readiness retry so the test stays fast.
+        datasourceMaxAttempts: 2, datasourceRetryDelayMs: 0,
       });
       expect(r.ok).toBe(false);
       expect(r.reason).toContain("datasource");
@@ -205,6 +207,88 @@ describe("registerAasCollection", () => {
     }
   });
 
+  test("polls the datasource until Grafana is ready, then registers", async () => {
+    // Grafana isn't ready on the first probes (no prometheus datasource yet),
+    // then it provisions — the readiness retry must keep going and then succeed.
+    let dsProbes = 0;
+    calls = [];
+    fetchSpy = spyOn(globalThis, "fetch").mockImplementation((async (input: unknown, init?: { method?: string; body?: string }) => {
+      const url = String(input);
+      const method = (init?.method || "GET").toUpperCase();
+      calls.push({ url, method, body: init?.body });
+      if (url.includes("/api/serviceaccounts/search")) return res(true, 200, { serviceAccounts: [] });
+      if (url.match(/\/tokens$/) && method === "POST") return res(true, 200, { key: "glsa_mock" });
+      if (url.endsWith("/api/serviceaccounts") && method === "POST") return res(true, 201, { id: 42 });
+      if (url.includes("/api/datasources")) {
+        dsProbes++;
+        return dsProbes < 3
+          ? res(true, 200, [{ id: 3, type: "loki" }]) // not ready yet
+          : res(true, 200, [{ id: 8, type: "prometheus" }, { id: 3, type: "loki" }]);
+      }
+      if (url.includes("/rpc/monitoring_instance_aas_register")) return res(true, 200, {});
+      return res(false, 404, {});
+    }) as unknown as typeof fetch);
+
+    const r = await registerAasCollection("apikey-1", "inst-123", {
+      grafanaPassword: "pw", instancesPath, vcpus: 8, apiBaseUrl: "https://api.test",
+      datasourceMaxAttempts: 6, datasourceRetryDelayMs: 0,
+    });
+    expect(r.ok).toBe(true);
+    expect(dsProbes).toBeGreaterThanOrEqual(3); // kept polling past the not-ready probes
+    const rpc = calls.find((c) => c.url.includes("/rpc/monitoring_instance_aas_register"));
+    expect(rpc).toBeDefined();
+    expect(JSON.parse(rpc!.body!).datasource_id).toBe(8);
+  });
+
+  test(">1 prometheus datasource is a definitive skip: one probe, no retry", async () => {
+    // The >1 case is permanent (the datasource count only grows), so the
+    // readiness loop must bail after a single probe, not burn its whole budget.
+    let dsProbes = 0;
+    calls = [];
+    fetchSpy = spyOn(globalThis, "fetch").mockImplementation((async (input: unknown, init?: { method?: string; body?: string }) => {
+      const url = String(input);
+      const method = (init?.method || "GET").toUpperCase();
+      calls.push({ url, method, body: init?.body });
+      if (url.includes("/api/datasources")) {
+        dsProbes++;
+        return res(true, 200, [{ id: 8, type: "prometheus" }, { id: 9, type: "prometheus" }, { id: 3, type: "loki" }]);
+      }
+      return res(false, 404, {});
+    }) as unknown as typeof fetch);
+
+    const r = await registerAasCollection("apikey-1", "inst-123", {
+      grafanaPassword: "pw", instancesPath, vcpus: 8, apiBaseUrl: "https://api.test",
+      datasourceMaxAttempts: 5, datasourceRetryDelayMs: 0,
+    });
+    expect(r.ok).toBe(false);
+    expect(r.reason).toContain("datasource");
+    expect(dsProbes).toBe(1); // bailed after one probe; did NOT retry 5x
+    expect(calls.some((c) => c.url.includes("/rpc/monitoring_instance_aas_register"))).toBe(false);
+  });
+
+  test("never-ready datasource: polls exactly maxAttempts times, then ok:false", async () => {
+    // Bounds the readiness loop: a never-appearing datasource must probe exactly
+    // maxAttempts times (N probes, N-1 sleeps) and then give up — not loop forever.
+    let dsProbes = 0;
+    calls = [];
+    fetchSpy = spyOn(globalThis, "fetch").mockImplementation((async (input: unknown, init?: { method?: string; body?: string }) => {
+      const url = String(input);
+      const method = (init?.method || "GET").toUpperCase();
+      calls.push({ url, method, body: init?.body });
+      if (url.includes("/api/datasources")) { dsProbes++; return res(true, 200, [{ id: 3, type: "loki" }]); } // never a prometheus
+      return res(false, 404, {});
+    }) as unknown as typeof fetch);
+
+    const r = await registerAasCollection("apikey-1", "inst-123", {
+      grafanaPassword: "pw", instancesPath, vcpus: 8, apiBaseUrl: "https://api.test",
+      datasourceMaxAttempts: 3, datasourceRetryDelayMs: 0,
+    });
+    expect(r.ok).toBe(false);
+    expect(r.reason).toContain("datasource");
+    expect(dsProbes).toBe(3); // bounded: exactly maxAttempts probes
+    expect(calls.some((c) => c.url.includes("/rpc/monitoring_instance_aas_register"))).toBe(false);
+  });
+
   test("mint returning no key → ok:false, no RPC call", async () => {
     installFetch({ mintKey: null });
     const r = await registerAasCollection("apikey-1", "inst-123", {

package/test/monitoring.test.ts

@@ -19,6 +19,7 @@ import {
 import {
   registerMonitoringInstance,
   resolveAdoptedProject,
+  planMonitoringRegistration,
 } from "../bin/postgres-ai";
 
 /**
@@ -241,12 +242,13 @@ describe("registerMonitoringInstance", () => {
   });
 
   // Issue platform-all#311: console-provisioned installs pass instance_id so
-  // the platform adopts the provisioned instance instead of self-registering
-  // a duplicate under an auto-created "postgres-ai-monitoring" project.
+  // the platform adopts the provisioned instance and returns its real project
+  // — the CLI sends NO project_name on the adopt path (the hardcoded
+  // "postgres-ai-monitoring" default was removed).
   test("includes instance_id in body when adopting a provisioned instance", async () => {
     const instanceId = "019eb300-3f2a-7a75-b54d-4f10572b25b8";
 
-    await registerMonitoringInstance("key", "postgres-ai-monitoring", opts({ instanceId }));
+    await registerMonitoringInstance("key", undefined, opts({ instanceId }));
 
     const body = JSON.parse(fetchCalls[0].options.body as string);
     expect(body.instance_id).toBe(instanceId);
@@ -255,6 +257,22 @@ describe("registerMonitoringInstance", () => {
     expect(headers["instance-id"]).toBeUndefined();
   });
 
+  test("omits project_name from the body when undefined (adopt path)", async () => {
+    await registerMonitoringInstance("key", undefined, opts({ instanceId: "i" }));
+
+    const body = JSON.parse(fetchCalls[0].options.body as string);
+    // The adopt path sends no name; the platform returns the real project.
+    expect("project_name" in body).toBe(false);
+    expect(body.api_token).toBe("key");
+  });
+
+  test("omits project_name from the body when empty/whitespace", async () => {
+    await registerMonitoringInstance("key", "   ", opts({ instanceId: "i" }));
+
+    const body = JSON.parse(fetchCalls[0].options.body as string);
+    expect("project_name" in body).toBe(false);
+  });
+
   test("omits instance_id from the body for legacy self-registration", async () => {
     await registerMonitoringInstance("key", "my-project", opts());
 
@@ -262,6 +280,8 @@ describe("registerMonitoringInstance", () => {
     // PostgREST matches the 3-arg function via its default — the key must be
     // ABSENT (not null) so legacy CLIs and the new one hit the same overload.
     expect("instance_id" in body).toBe(false);
+    // A real project name still rides in the body for legacy registration.
+    expect(body.project_name).toBe("my-project");
   });
 
   test("a 200 with {project_id, project_name} returns a populated result", async () => {
@@ -323,6 +343,37 @@ describe("registerMonitoringInstance", () => {
   });
 });
 
+describe("planMonitoringRegistration — mon local-install registration decision", () => {
+  test("instance id present → adopt, no project name required", () => {
+    const plan = planMonitoringRegistration({ instanceId: "i-123" });
+    expect(plan.kind).toBe("adopt");
+    expect(plan.projectName).toBeUndefined();
+  });
+
+  test("instance id present + project → adopt, carries the trimmed name", () => {
+    const plan = planMonitoringRegistration({ instanceId: "i-123", project: "  prod-db  " });
+    expect(plan.kind).toBe("adopt");
+    expect(plan.projectName).toBe("prod-db");
+  });
+
+  test("no instance id + no project → error-missing-project (exit 1 path)", () => {
+    const plan = planMonitoringRegistration({});
+    expect(plan.kind).toBe("error-missing-project");
+    expect(plan.projectName).toBeUndefined();
+  });
+
+  test("no instance id + empty/whitespace project → error-missing-project", () => {
+    expect(planMonitoringRegistration({ project: "" }).kind).toBe("error-missing-project");
+    expect(planMonitoringRegistration({ project: "   " }).kind).toBe("error-missing-project");
+  });
+
+  test("no instance id + real project → legacy self-register with the trimmed name", () => {
+    const plan = planMonitoringRegistration({ project: "  my-project  " });
+    expect(plan.kind).toBe("self-register");
+    expect(plan.projectName).toBe("my-project");
+  });
+});
+
 describe("resolveAdoptedProject — what gets persisted to .pgwatch-config", () => {
   test("prefers the numeric project_id over the name (survives renames)", () => {
     expect(resolveAdoptedProject({ projectId: 42, projectName: "prod-db" })).toBe("42");