postgresai 0.16.0-dev.5 → 0.16.0-dev.7

package/bin/postgres-ai.ts

@@ -5424,7 +5424,7 @@ interface JoeCliOpts {
 // ============================================================================
 // DBLab companion command surface (Joe API v2 · SPEC §8)
 //
-// `pgai clone|branch|snapshot …` proxy the SAME Platform DBLab API the Console
+// `pgai dblab clone|branch|snapshot …` proxy the SAME Platform DBLab API the Console
 // already drives (v1.dblab_api_call). Every verb is `--project <id|alias>`
 // scoped: the project's single DBLab instance is resolved server-side listing,
 // then the verb is proxied. Destructive verbs (clone reset/destroy, branch
@@ -5465,7 +5465,7 @@ function printJoeOutcome(command: JoeCommand, outcome: ExecuteJoeOutcome, json:
             status: outcome.status,
             session_id: outcome.sessionId,
             budget_expired: true,
-            resume: `pgai result ${outcome.commandId}`,
+            resume: `pgai joe result ${outcome.commandId}`,
           },
           null,
           2
@@ -5473,7 +5473,7 @@ function printJoeOutcome(command: JoeCommand, outcome: ExecuteJoeOutcome, json:
       );
     } else {
       console.log(
-        `submitted ${outcome.commandId} · ${outcome.status} · budget ${budgetSeconds}s reached — resume:  pgai result ${outcome.commandId}`
+        `submitted ${outcome.commandId} · ${outcome.status} · budget ${budgetSeconds}s reached — resume:  pgai joe result ${outcome.commandId}`
       );
     }
     return;
@@ -5501,7 +5501,7 @@ function printJoeOutcome(command: JoeCommand, outcome: ExecuteJoeOutcome, json:
   // Server-side timed_out (the dispatcher gave up). The genuine reply may still
   // land; suggest a resume, but signal failure with a non-zero exit.
   console.error(
-    `command ${outcome.commandId} timed out on the server — resume:  pgai result ${outcome.commandId}`
+    `command ${outcome.commandId} timed out on the server — resume:  pgai joe result ${outcome.commandId}`
   );
   process.exitCode = 1;
 }
@@ -5564,8 +5564,17 @@ function withJoeOptions(cmd: import("commander").Command): import("commander").C
     .option("--json", "output raw JSON");
 }
 
+// ---------------------------------------------------------------------------
+// Joe command group — every Joe verb lives under `pgai joe <verb>` (grouped CLI,
+// USER-AUTHORIZED restructure). The MCP tool names stay flat/unchanged; only the
+// CLI invocation path is grouped. `projects` stays top-level (org-level, SPEC §6).
+// ---------------------------------------------------------------------------
+const joe = program
+  .command("joe")
+  .description("Joe API v2 — plan/EXPLAIN/exec queries on ephemeral DBLab clones");
+
 withJoeOptions(
-  program
+  joe
     .command("plan <sql>")
     .description("plan a query (EXPLAIN, plan-only — no execution; the fast/safe default)")
 ).action(async (sql: string, opts: JoeCliOpts) => {
@@ -5573,7 +5582,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("explain <sql>")
     .description("EXPLAIN ANALYZE a query (EXECUTES on the hardened, ephemeral clone)")
 ).action(async (sql: string, opts: JoeCliOpts) => {
@@ -5581,7 +5590,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("exec <sql>")
     .description("run arbitrary DDL/DML on the clone (e.g. create index, analyze)")
 ).action(async (sql: string, opts: JoeCliOpts) => {
@@ -5589,7 +5598,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("hypo <indexSql>")
     .description("HypoPG hypothetical index + re-plan (no real index, no data change)")
     .requiredOption("--query <sql>", "target query the hypothetical index is evaluated against")
@@ -5598,7 +5607,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("activity")
     .description("running-activity snapshot (pg_stat_activity; query text redacted)")
 ).action(async (opts: JoeCliOpts) => {
@@ -5606,7 +5615,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("terminate <pid>")
     .description("pg_terminate_backend(pid) on the clone")
 ).action(async (pid: string, opts: JoeCliOpts) => {
@@ -5620,7 +5629,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("reset")
     .description("reset/recreate the session's thin clone")
 ).action(async (opts: JoeCliOpts) => {
@@ -5628,7 +5637,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("describe <object>")
     .description("\\d-family schema/relation/index metadata")
     .option("--variant <variant>", "\\d-family variant (e.g. \\d+, \\di, \\dt)")
@@ -5699,9 +5708,18 @@ async function resolveDblabTarget(
   return { apiKey, apiBaseUrl, orgId, instanceId };
 }
 
+// ---------------------------------------------------------------------------
+// DBLab command group — every DBLab verb lives under
+// `pgai dblab <clone|branch|snapshot> …` (grouped CLI, USER-AUTHORIZED restructure).
+// MCP tool names (clone_create/…) stay flat/unchanged; only the CLI path is grouped.
+// ---------------------------------------------------------------------------
+const dblab = program
+  .command("dblab")
+  .description("DBLab thin-clone / branch / snapshot management (proxies the Platform DBLab API)");
+
 // ---- clone ----------------------------------------------------------------
 
-const clone = program.command("clone").description("DBLab thin-clone management (proxies the Platform DBLab API)");
+const clone = dblab.command("clone").description("DBLab thin-clone management (proxies the Platform DBLab API)");
 
 clone
   .command("create")
@@ -5735,8 +5753,9 @@ clone
     }
   });
 
-// Resume / inspect a previously submitted command by id.
-program
+// Resume / inspect a previously submitted command by id. Part of the `joe` group
+// (`pgai joe status <commandId>`) — distinct from `pgai dblab clone status <cloneId>`.
+joe
   .command("status <commandId>")
   .description("show a Joe command's status (metadata only)")
   .option("--debug", "enable debug output")
@@ -5782,7 +5801,7 @@ clone
     }
   });
 
-program
+joe
   .command("result <commandId>")
   .description("fetch a Joe command's result by id (resume a timed-out one-shot)")
   .option("--debug", "enable debug output")
@@ -5881,7 +5900,7 @@ clone
 
 // ---- branch ---------------------------------------------------------------
 
-const branch = program.command("branch").description("DBLab branch management (proxies the Platform DBLab API)");
+const branch = dblab.command("branch").description("DBLab branch management (proxies the Platform DBLab API)");
 
 branch
   .command("list")
@@ -5961,7 +5980,7 @@ branch
 
 // ---- snapshot -------------------------------------------------------------
 
-const snapshot = program.command("snapshot").description("DBLab snapshot management (proxies the Platform DBLab API)");
+const snapshot = dblab.command("snapshot").description("DBLab snapshot management (proxies the Platform DBLab API)");
 
 snapshot
   .command("list")

package/dist/bin/postgres-ai.js

@@ -13331,33 +13331,38 @@ function isHtmlContent2(text) {
   const trimmed = text.trim();
   return trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html") || trimmed.startsWith("<HTML");
 }
-function formatHttpError2(operation, status, responseBody) {
-  const statusMessage = HTTP_STATUS_MESSAGES2[status] || "Request failed";
-  let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+function formatHttpError2(operation, status, responseBody, statusText) {
+  const generic = HTTP_STATUS_MESSAGES2[status] || "Request failed";
   const remediation = status === 401 ? `
 ${AUTH_REMEDIATION_HINT2}` : "";
-  if (responseBody) {
-    if (isHtmlContent2(responseBody)) {
-      return errMsg + remediation;
-    }
+  let bodyMessage;
+  let bodyDetails;
+  if (responseBody && !isHtmlContent2(responseBody)) {
     try {
       const errObj = JSON.parse(responseBody);
-      const message = errObj.message || errObj.error || errObj.detail;
-      if (message && typeof message === "string") {
-        errMsg += `
-${message}`;
-      } else {
-        errMsg += `
-${JSON.stringify(errObj, null, 2)}`;
+      const message = errObj.message ?? errObj.error;
+      if (typeof message === "string" && message.trim().length > 0) {
+        bodyMessage = message.trim();
+      }
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = details.trim();
       }
     } catch {
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `
-${trimmed}`;
+        bodyDetails = trimmed;
       }
     }
   }
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase = trimmedReason && trimmedReason !== STANDARD_REASON_PHRASES2[status] && trimmedReason !== generic ? trimmedReason : undefined;
+  const headline = bodyMessage ?? reasonPhrase ?? generic;
+  let errMsg = `${operation}: HTTP ${status} - ${headline}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `
+${bodyDetails}`;
+  }
   return errMsg + remediation;
 }
 function maskSecret2(secret) {
@@ -13391,7 +13396,7 @@ function resolveBaseUrls2(opts, cfg, defaults2 = {}) {
     storageBaseUrl: normalizeBaseUrl2(storageCandidate)
   };
 }
-var HTTP_STATUS_MESSAGES2, AUTH_REMEDIATION_HINT2 = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
+var HTTP_STATUS_MESSAGES2, AUTH_REMEDIATION_HINT2 = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.", STANDARD_REASON_PHRASES2;
 var init_util = __esm(() => {
   HTTP_STATUS_MESSAGES2 = {
     400: "Bad Request",
@@ -13405,6 +13410,20 @@ var init_util = __esm(() => {
     503: "Service Unavailable - server temporarily unavailable",
     504: "Gateway Timeout - server temporarily unavailable"
   };
+  STANDARD_REASON_PHRASES2 = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    408: "Request Timeout",
+    409: "Conflict",
+    413: "Payload Too Large",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout"
+  };
 });
 
 // node_modules/commander/esm.mjs
@@ -13425,7 +13444,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.16.0-dev.5",
+  version: "0.16.0-dev.7",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16256,7 +16275,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.5";
+var version = "0.16.0-dev.7";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -16398,33 +16417,52 @@ function isHtmlContent(text) {
   return trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html") || trimmed.startsWith("<HTML");
 }
 var AUTH_REMEDIATION_HINT = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
-function formatHttpError(operation, status, responseBody) {
-  const statusMessage = HTTP_STATUS_MESSAGES[status] || "Request failed";
-  let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+var STANDARD_REASON_PHRASES = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  408: "Request Timeout",
+  409: "Conflict",
+  413: "Payload Too Large",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout"
+};
+function formatHttpError(operation, status, responseBody, statusText) {
+  const generic = HTTP_STATUS_MESSAGES[status] || "Request failed";
   const remediation = status === 401 ? `
 ${AUTH_REMEDIATION_HINT}` : "";
-  if (responseBody) {
-    if (isHtmlContent(responseBody)) {
-      return errMsg + remediation;
-    }
+  let bodyMessage;
+  let bodyDetails;
+  if (responseBody && !isHtmlContent(responseBody)) {
     try {
       const errObj = JSON.parse(responseBody);
-      const message = errObj.message || errObj.error || errObj.detail;
-      if (message && typeof message === "string") {
-        errMsg += `
-${message}`;
-      } else {
-        errMsg += `
-${JSON.stringify(errObj, null, 2)}`;
+      const message = errObj.message ?? errObj.error;
+      if (typeof message === "string" && message.trim().length > 0) {
+        bodyMessage = message.trim();
+      }
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = details.trim();
       }
     } catch {
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `
-${trimmed}`;
+        bodyDetails = trimmed;
       }
     }
   }
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase = trimmedReason && trimmedReason !== STANDARD_REASON_PHRASES[status] && trimmedReason !== generic ? trimmedReason : undefined;
+  const headline = bodyMessage ?? reasonPhrase ?? generic;
+  let errMsg = `${operation}: HTTP ${status} - ${headline}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `
+${bodyDetails}`;
+  }
   return errMsg + remediation;
 }
 function maskSecret(secret) {
@@ -17330,7 +17368,7 @@ async function callRpc(params) {
     console.error(`Debug: Response body: ${text}`);
   }
   if (!response.ok) {
-    throw new Error(formatHttpError(operation, response.status, text));
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
   }
   try {
     return JSON.parse(text);
@@ -17655,7 +17693,7 @@ async function callDblabApi(params) {
     console.error(`Debug: Response body: ${text}`);
   }
   if (!response.ok) {
-    throw new Error(formatHttpError(operation, response.status, text));
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
   }
   if (text.trim() === "") {
     return null;
@@ -25145,7 +25183,7 @@ async function runJoeTool(params) {
     session_id: outcome.sessionId,
     status: outcome.status,
     budget_expired: outcome.budgetExpired,
-    resume: outcome.budgetExpired ? `pgai result ${outcome.commandId}` : undefined,
+    resume: outcome.budgetExpired ? `pgai joe result ${outcome.commandId}` : undefined,
     result: outcome.result
   };
   const isError = outcome.status === "error" || outcome.status === "timed_out";
@@ -26982,7 +27020,7 @@ async function callRpc2(params) {
     console.error(`Debug: Response body: ${text}`);
   }
   if (!response.ok) {
-    throw new Error(formatHttpError(operation, response.status, text));
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
   }
   try {
     return JSON.parse(text);
@@ -27393,7 +27431,7 @@ async function callDblabApi2(params) {
     console.error(`Debug: Response body: ${text}`);
   }
   if (!response.ok) {
-    throw new Error(formatHttpError(operation, response.status, text));
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
   }
   if (text.trim() === "") {
     return null;
@@ -39715,10 +39753,10 @@ function printJoeOutcome(command, outcome, json3) {
         status: outcome.status,
         session_id: outcome.sessionId,
         budget_expired: true,
-        resume: `pgai result ${outcome.commandId}`
+        resume: `pgai joe result ${outcome.commandId}`
       }, null, 2));
     } else {
-      console.log(`submitted ${outcome.commandId} \xB7 ${outcome.status} \xB7 budget ${budgetSeconds}s reached \u2014 resume:  pgai result ${outcome.commandId}`);
+      console.log(`submitted ${outcome.commandId} \xB7 ${outcome.status} \xB7 budget ${budgetSeconds}s reached \u2014 resume:  pgai joe result ${outcome.commandId}`);
     }
     return;
   }
@@ -39740,7 +39778,7 @@ function printJoeOutcome(command, outcome, json3) {
     process.exitCode = 1;
     return;
   }
-  console.error(`command ${outcome.commandId} timed out on the server \u2014 resume:  pgai result ${outcome.commandId}`);
+  console.error(`command ${outcome.commandId} timed out on the server \u2014 resume:  pgai joe result ${outcome.commandId}`);
   process.exitCode = 1;
 }
 async function runJoeCli(command, sql, args, opts) {
@@ -39784,22 +39822,23 @@ async function runJoeCli(command, sql, args, opts) {
 function withJoeOptions(cmd) {
   return cmd.option("--project <id|alias>", "target project by numeric id OR alias/name").option("--session <id>", "run on a specific session's clone").option("--new-session", "start a fresh session/clone (null session)").option("--budget <seconds>", "one-shot poll budget in seconds (default 25)", (v) => parseInt(v, 10)).option("--debug", "enable debug output").option("--json", "output raw JSON");
 }
-withJoeOptions(program2.command("plan <sql>").description("plan a query (EXPLAIN, plan-only \u2014 no execution; the fast/safe default)")).action(async (sql, opts) => {
+var joe = program2.command("joe").description("Joe API v2 \u2014 plan/EXPLAIN/exec queries on ephemeral DBLab clones");
+withJoeOptions(joe.command("plan <sql>").description("plan a query (EXPLAIN, plan-only \u2014 no execution; the fast/safe default)")).action(async (sql, opts) => {
   await runJoeCli("plan", sql, null, opts);
 });
-withJoeOptions(program2.command("explain <sql>").description("EXPLAIN ANALYZE a query (EXECUTES on the hardened, ephemeral clone)")).action(async (sql, opts) => {
+withJoeOptions(joe.command("explain <sql>").description("EXPLAIN ANALYZE a query (EXECUTES on the hardened, ephemeral clone)")).action(async (sql, opts) => {
   await runJoeCli("explain", sql, null, opts);
 });
-withJoeOptions(program2.command("exec <sql>").description("run arbitrary DDL/DML on the clone (e.g. create index, analyze)")).action(async (sql, opts) => {
+withJoeOptions(joe.command("exec <sql>").description("run arbitrary DDL/DML on the clone (e.g. create index, analyze)")).action(async (sql, opts) => {
   await runJoeCli("exec", sql, null, opts);
 });
-withJoeOptions(program2.command("hypo <indexSql>").description("HypoPG hypothetical index + re-plan (no real index, no data change)").requiredOption("--query <sql>", "target query the hypothetical index is evaluated against")).action(async (indexSql, opts) => {
+withJoeOptions(joe.command("hypo <indexSql>").description("HypoPG hypothetical index + re-plan (no real index, no data change)").requiredOption("--query <sql>", "target query the hypothetical index is evaluated against")).action(async (indexSql, opts) => {
   await runJoeCli("hypo", indexSql, { query: opts.query }, opts);
 });
-withJoeOptions(program2.command("activity").description("running-activity snapshot (pg_stat_activity; query text redacted)")).action(async (opts) => {
+withJoeOptions(joe.command("activity").description("running-activity snapshot (pg_stat_activity; query text redacted)")).action(async (opts) => {
   await runJoeCli("activity", null, null, opts);
 });
-withJoeOptions(program2.command("terminate <pid>").description("pg_terminate_backend(pid) on the clone")).action(async (pid, opts) => {
+withJoeOptions(joe.command("terminate <pid>").description("pg_terminate_backend(pid) on the clone")).action(async (pid, opts) => {
   const pidNum = parseInt(pid, 10);
   if (Number.isNaN(pidNum)) {
     console.error("pid must be a number");
@@ -39808,10 +39847,10 @@ withJoeOptions(program2.command("terminate <pid>").description("pg_terminate_bac
   }
   await runJoeCli("terminate", null, { pid: pidNum }, opts);
 });
-withJoeOptions(program2.command("reset").description("reset/recreate the session's thin clone")).action(async (opts) => {
+withJoeOptions(joe.command("reset").description("reset/recreate the session's thin clone")).action(async (opts) => {
   await runJoeCli("reset", null, null, opts);
 });
-withJoeOptions(program2.command("describe <object>").description("\\d-family schema/relation/index metadata").option("--variant <variant>", "\\d-family variant (e.g. \\d+, \\di, \\dt)")).action(async (object4, opts) => {
+withJoeOptions(joe.command("describe <object>").description("\\d-family schema/relation/index metadata").option("--variant <variant>", "\\d-family variant (e.g. \\d+, \\di, \\dt)")).action(async (object4, opts) => {
   const args = { object: object4 };
   if (opts.variant)
     args.variant = opts.variant;
@@ -39861,7 +39900,8 @@ async function resolveDblabTarget(project, debug) {
   const instanceId = await resolveDblabInstanceId2({ apiKey, apiBaseUrl, project: ref, orgId, debug });
   return { apiKey, apiBaseUrl, orgId, instanceId };
 }
-var clone2 = program2.command("clone").description("DBLab thin-clone management (proxies the Platform DBLab API)");
+var dblab = program2.command("dblab").description("DBLab thin-clone / branch / snapshot management (proxies the Platform DBLab API)");
+var clone2 = dblab.command("clone").description("DBLab thin-clone management (proxies the Platform DBLab API)");
 clone2.command("create").description("create a thin clone of the project's database").requiredOption("--project <id|alias>", "project id or alias").option("--branch <branch>", "branch to clone from").option("--snapshot <id>", "snapshot id to clone from").option("--id <id>", "clone id (DBLab generates one when omitted)").option("--db-user <user>", "clone DB user").option("--db-password <password>", "clone DB password").option("--protected", "protect the clone from auto-deletion").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
   try {
     const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
@@ -39883,7 +39923,7 @@ clone2.command("create").description("create a thin clone of the project's datab
     process.exitCode = 1;
   }
 });
-program2.command("status <commandId>").description("show a Joe command's status (metadata only)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (commandId, opts) => {
+joe.command("status <commandId>").description("show a Joe command's status (metadata only)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (commandId, opts) => {
   try {
     const rootOpts = program2.opts();
     const cfg = readConfig();
@@ -39916,7 +39956,7 @@ clone2.command("list").description("list the project's thin clones").requiredOpt
     process.exitCode = 1;
   }
 });
-program2.command("result <commandId>").description("fetch a Joe command's result by id (resume a timed-out one-shot)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (commandId, opts) => {
+joe.command("result <commandId>").description("fetch a Joe command's result by id (resume a timed-out one-shot)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (commandId, opts) => {
   try {
     const rootOpts = program2.opts();
     const cfg = readConfig();
@@ -39988,7 +40028,7 @@ clone2.command("destroy <cloneId>").description("destroy a clone (requires joe:a
     process.exitCode = 1;
   }
 });
-var branch = program2.command("branch").description("DBLab branch management (proxies the Platform DBLab API)");
+var branch = dblab.command("branch").description("DBLab branch management (proxies the Platform DBLab API)");
 branch.command("list").description("list the project's branches").requiredOption("--project <id|alias>", "project id or alias").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
   try {
     const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
@@ -40037,7 +40077,7 @@ branch.command("log <name>").description("show a branch's snapshot log").require
     process.exitCode = 1;
   }
 });
-var snapshot = program2.command("snapshot").description("DBLab snapshot management (proxies the Platform DBLab API)");
+var snapshot = dblab.command("snapshot").description("DBLab snapshot management (proxies the Platform DBLab API)");
 snapshot.command("list").description("list the project's snapshots").requiredOption("--project <id|alias>", "project id or alias").option("--branch <branch>", "filter by branch").option("--dataset <dataset>", "filter by dataset").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
   try {
     const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);

package/lib/dblab.ts

@@ -196,8 +196,10 @@ async function callDblabApi<T>(params: DblabApiCallParams): Promise<T> {
 
   if (!response.ok) {
     // PostgREST maps custom `PTxyz` sqlstates to HTTP status `xyz`, so a missing
-    // `joe:admin` scope on a destructive verb surfaces here as HTTP 403.
-    throw new Error(formatHttpError(operation, response.status, text));
+    // `joe:admin` scope on a destructive verb surfaces here as HTTP 403. The
+    // RPC's user-facing message rides in the HTTP reason phrase (statusText),
+    // not the JSON body — pass it through.
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
   }
 
   // Some DBLab actions (reset/destroy) reply with an empty body on success.

package/lib/joe.ts

@@ -177,9 +177,10 @@ async function callRpc<T>(params: RpcCallParams): Promise<T> {
 
   if (!response.ok) {
     // PostgREST maps a custom `PTxyz` sqlstate to HTTP status `xyz`, so PT403 →
-    // HTTP 403, PT404 → 404, PT429 → 429, etc. formatHttpError surfaces the JSON
-    // `message` (e.g. the "AI features disabled for this org" text for AC36).
-    throw new Error(formatHttpError(operation, response.status, text));
+    // HTTP 403, PT404 → 404, PT429 → 429, etc. The RPC's user-facing message
+    // (e.g. the "AI features disabled for this org" text for AC36) rides in the
+    // HTTP reason phrase (statusText), not the JSON body — pass it through.
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
   }
 
   try {
@@ -496,7 +497,7 @@ const defaultSleep = (ms: number): Promise<void> => new Promise((r) => setTimeou
 /**
  * Submit a command then client-side poll status/result within the one-shot budget.
  * On a terminal state returns the result; on budget expiry returns a resume handle
- * (`budgetExpired: true`) so the caller can `pgai result <command_id>` later.
+ * (`budgetExpired: true`) so the caller can `pgai joe result <command_id>` later.
  */
 export async function runCommand(params: RunCommandParams): Promise<RunCommandOutcome> {
   const {

package/lib/mcp-server.ts

@@ -284,7 +284,7 @@ async function runJoeTool(params: RunJoeToolParams): Promise<McpToolResponse> {
     session_id: outcome.sessionId,
     status: outcome.status,
     budget_expired: outcome.budgetExpired,
-    resume: outcome.budgetExpired ? `pgai result ${outcome.commandId}` : undefined,
+    resume: outcome.budgetExpired ? `pgai joe result ${outcome.commandId}` : undefined,
     result: outcome.result,
   };
   const isError = outcome.status === "error" || outcome.status === "timed_out";
@@ -648,7 +648,7 @@ export async function handleToolCall(
     }
 
     // ---- DBLab companion tools (SPEC §8) --------------------------------
-    // Each mirrors the CLI `pgai clone|branch|snapshot …` verb 1:1: resolve the
+    // Each mirrors the CLI `pgai dblab clone|branch|snapshot …` verb 1:1: resolve the
     // project's single DBLab instance, then proxy the existing Platform DBLab
     // API (v1.dblab_api_call). Destructive verbs are `joe:admin`-gated backend
     // side (a PT403 surfaces as an isError response via the outer catch).
@@ -1058,7 +1058,7 @@ export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?:
         },
         ...joeToolDefinitions(),
         // DBLab companion tools (SPEC §8) — proxy the existing Platform DBLab API
-        // (v1.dblab_api_call) the Console drives; mirror `pgai clone|branch|snapshot`.
+        // (v1.dblab_api_call) the Console drives; mirror `pgai dblab clone|branch|snapshot`.
         // `project` (id or alias) resolves the project's single DBLab instance.
         {
           name: "clone_create",

package/lib/util.ts

@@ -28,42 +28,91 @@ function isHtmlContent(text: string): boolean {
  */
 const AUTH_REMEDIATION_HINT = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
 
+/**
+ * Standard HTTP reason phrases we should NOT treat as a server-authored
+ * message: when the reason phrase equals the stock text for the status, it
+ * carries no extra information, so we prefer the friendlier generic label.
+ */
+const STANDARD_REASON_PHRASES: Record<number, string> = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  408: "Request Timeout",
+  409: "Conflict",
+  413: "Payload Too Large",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout",
+};
+
 /**
  * Format an HTTP error response into a clean, developer-friendly message.
  * Handles HTML error pages (e.g., from Cloudflare) by showing just the status code and message.
  * For 401 responses, appends a remediation hint pointing at `postgresai auth`.
+ *
+ * The platform's PostgREST layer uses the `PTxyz` custom-status convention:
+ * a raised `PT403`/`PT404`/… maps to the HTTP status and delivers the RPC's
+ * user-facing message in the HTTP **reason phrase** (`response.statusText`),
+ * NOT the JSON body — the body carries only `hint`/`details` (no `message`).
+ * So callers pass `statusText` and it is preferred over the built-in generic
+ * label. Headline precedence: JSON body `message` → custom reason phrase →
+ * generic label; the JSON `details` (plural, PostgREST's spelling) is shown as
+ * a supplementary line.
  */
-export function formatHttpError(operation: string, status: number, responseBody?: string): string {
-  const statusMessage = HTTP_STATUS_MESSAGES[status] || "Request failed";
-  let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+export function formatHttpError(
+  operation: string,
+  status: number,
+  responseBody?: string,
+  statusText?: string
+): string {
+  const generic = HTTP_STATUS_MESSAGES[status] || "Request failed";
   const remediation = status === 401 ? `\n${AUTH_REMEDIATION_HINT}` : "";
 
-  if (responseBody) {
-    // If it's HTML (like Cloudflare error pages), don't dump the raw HTML
-    if (isHtmlContent(responseBody)) {
-      // Just use the status message, don't append HTML
-      return errMsg + remediation;
-    }
+  let bodyMessage: string | undefined;
+  let bodyDetails: string | undefined;
 
-    // Try to parse as JSON for structured error info
+  if (responseBody && !isHtmlContent(responseBody)) {
+    // If it's HTML (like Cloudflare error pages), we fall through with no
+    // parsed fields and never dump the raw HTML.
     try {
       const errObj = JSON.parse(responseBody);
-      // Extract common error message fields
-      const message = errObj.message || errObj.error || errObj.detail;
-      if (message && typeof message === "string") {
-        errMsg += `\n${message}`;
-      } else {
-        errMsg += `\n${JSON.stringify(errObj, null, 2)}`;
+      const message = errObj.message ?? errObj.error;
+      if (typeof message === "string" && message.trim().length > 0) {
+        bodyMessage = message.trim();
+      }
+      // PostgREST spells it `details` (plural); accept `detail` too.
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = details.trim();
       }
     } catch {
-      // Plain text error - append it if it's short and useful
+      // Plain text error - treat it as the details line if short and useful.
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `\n${trimmed}`;
+        bodyDetails = trimmed;
       }
     }
   }
 
+  // A custom reason phrase (PTxyz message) is meaningful only when it differs
+  // from the stock HTTP reason phrase for this status.
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase =
+    trimmedReason &&
+    trimmedReason !== STANDARD_REASON_PHRASES[status] &&
+    trimmedReason !== generic
+      ? trimmedReason
+      : undefined;
+
+  const headline = bodyMessage ?? reasonPhrase ?? generic;
+  let errMsg = `${operation}: HTTP ${status} - ${headline}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `\n${bodyDetails}`;
+  }
+
   return errMsg + remediation;
 }
 

package/package.json

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

package/test/dblab.cli.test.ts

@@ -93,17 +93,24 @@ async function startFakeApi(projects?: unknown[]) {
   };
 }
 
-describe("CLI DBLab companion command groups", () => {
-  test("top-level help lists clone, branch, and snapshot groups", () => {
+describe("CLI DBLab companion command groups (grouped under `pgai dblab …`)", () => {
+  test("top-level help lists the dblab group", () => {
     const r = runCli(["--help"], isolatedEnv());
     const out = `${r.stdout}\n${r.stderr}`;
+    expect(out).toContain("dblab");
+  });
+
+  test("dblab help exposes the clone, branch, and snapshot groups", () => {
+    const r = runCli(["dblab", "--help"], isolatedEnv());
+    expect(r.status).toBe(0);
+    const out = `${r.stdout}\n${r.stderr}`;
     expect(out).toContain("clone");
     expect(out).toContain("branch");
     expect(out).toContain("snapshot");
   });
 
   test("clone help exposes create/list/status/reset/destroy", () => {
-    const r = runCli(["clone", "--help"], isolatedEnv());
+    const r = runCli(["dblab", "clone", "--help"], isolatedEnv());
     expect(r.status).toBe(0);
     const out = `${r.stdout}\n${r.stderr}`;
     expect(out).toContain("create");
@@ -114,7 +121,7 @@ describe("CLI DBLab companion command groups", () => {
   });
 
   test("branch help exposes list/create/delete/log", () => {
-    const r = runCli(["branch", "--help"], isolatedEnv());
+    const r = runCli(["dblab", "branch", "--help"], isolatedEnv());
     expect(r.status).toBe(0);
     const out = `${r.stdout}\n${r.stderr}`;
     expect(out).toContain("list");
@@ -124,7 +131,7 @@ describe("CLI DBLab companion command groups", () => {
   });
 
   test("snapshot help exposes list/create/destroy", () => {
-    const r = runCli(["snapshot", "--help"], isolatedEnv());
+    const r = runCli(["dblab", "snapshot", "--help"], isolatedEnv());
     expect(r.status).toBe(0);
     const out = `${r.stdout}\n${r.stderr}`;
     expect(out).toContain("list");
@@ -133,13 +140,13 @@ describe("CLI DBLab companion command groups", () => {
   });
 
   test("clone create fails fast without an API key", () => {
-    const r = runCli(["clone", "create", "--project", "main-db"], isolatedEnv());
+    const r = runCli(["dblab", "clone", "create", "--project", "main-db"], isolatedEnv());
     expect(r.status).toBe(1);
     expect(`${r.stdout}\n${r.stderr}`).toContain("API key is required");
   });
 
   test("clone list without --project errors", () => {
-    const r = runCli(["clone", "list"], isolatedEnv({ PGAI_API_KEY: "test-key" }));
+    const r = runCli(["dblab", "clone", "list"], isolatedEnv({ PGAI_API_KEY: "test-key" }));
     expect(r.status).not.toBe(0);
     expect(`${r.stdout}\n${r.stderr}`.toLowerCase()).toContain("project");
   });
@@ -148,7 +155,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["clone", "create", "--project", "main-db", "--json"],
+        ["dblab", "clone", "create", "--project", "main-db", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -170,7 +177,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["clone", "create", "--project", "main-db", "--branch", "feature-idx", "--snapshot", "s-9", "--protected", "--json"],
+        ["dblab", "clone", "create", "--project", "main-db", "--branch", "feature-idx", "--snapshot", "s-9", "--protected", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -185,7 +192,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["clone", "reset", "c-8f21", "--project", "main-db", "--json"],
+        ["dblab", "clone", "reset", "c-8f21", "--project", "main-db", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -202,7 +209,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["clone", "destroy", "c-8f21", "--project", "12", "--json"],
+        ["dblab", "clone", "destroy", "c-8f21", "--project", "12", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -219,7 +226,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["branch", "create", "feature-idx", "--project", "main-db", "--snapshot", "latest", "--json"],
+        ["dblab", "branch", "create", "feature-idx", "--project", "main-db", "--snapshot", "latest", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -236,7 +243,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["branch", "log", "feature-idx", "--project", "main-db", "--json"],
+        ["dblab", "branch", "log", "feature-idx", "--project", "main-db", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -252,7 +259,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["snapshot", "list", "--project", "main-db", "--json"],
+        ["dblab", "snapshot", "list", "--project", "main-db", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -268,7 +275,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["snapshot", "create", "--project", "main-db", "--clone", "c-8f21", "--message", "before idx", "--json"],
+        ["dblab", "snapshot", "create", "--project", "main-db", "--clone", "c-8f21", "--message", "before idx", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -284,7 +291,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["snapshot", "destroy", "s-1", "--project", "main-db", "--force", "--json"],
+        ["dblab", "snapshot", "destroy", "s-1", "--project", "main-db", "--force", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -300,7 +307,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["clone", "list", "--project", "does-not-exist"],
+        ["dblab", "clone", "list", "--project", "does-not-exist"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(1);
@@ -327,7 +334,7 @@ describe("CLI DBLab companion command groups", () => {
     try {
       const baseUrl = `http://${server.hostname}:${server.port}/api/general`;
       const r = await runCliAsync(
-        ["clone", "destroy", "c-1", "--project", "main-db"],
+        ["dblab", "clone", "destroy", "c-1", "--project", "main-db"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: baseUrl })
       );
       expect(r.status).toBe(1);

package/test/joe.cli.test.ts

@@ -126,11 +126,22 @@ function startFakeApi() {
   return { baseUrl, requests, stop: () => server.stop(true) };
 }
 
-describe("CLI Joe command surface", () => {
-  test("top-level help lists the Joe verbs and projects/result", () => {
+describe("CLI Joe command surface (grouped under `pgai joe …`)", () => {
+  test("top-level help lists the joe + dblab groups and top-level projects", () => {
     const r = runCli(["--help"], isolatedEnv());
     const out = `${r.stdout}\n${r.stderr}`;
-    for (const verb of ["plan", "explain", "exec", "hypo", "activity", "terminate", "reset", "describe", "projects", "result", "status"]) {
+    // Joe verbs are grouped under `joe`; DBLab verbs under `dblab`. `projects`
+    // stays top-level (org-level, not a Joe endpoint).
+    for (const group of ["joe", "dblab", "projects"]) {
+      expect(out).toContain(group);
+    }
+  });
+
+  test("pgai joe --help lists all the Joe verbs", () => {
+    const r = runCli(["joe", "--help"], isolatedEnv());
+    expect(r.status).toBe(0);
+    const out = `${r.stdout}\n${r.stderr}`;
+    for (const verb of ["plan", "explain", "exec", "hypo", "activity", "terminate", "reset", "describe", "result", "status"]) {
       expect(out).toContain(verb);
     }
   });
@@ -153,11 +164,11 @@ describe("CLI Joe command surface", () => {
     }
   });
 
-  test("pgai plan --project 12 submits command='plan' and prints the plan", async () => {
+  test("pgai joe plan --project 12 submits command='plan' and prints the plan", async () => {
     const api = startFakeApi();
     try {
       const r = await runCliAsync(
-        ["plan", "select * from users where email = 'x@acme.io'", "--project", "12"],
+        ["joe", "plan", "select * from users where email = 'x@acme.io'", "--project", "12"],
         isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -174,11 +185,11 @@ describe("CLI Joe command surface", () => {
     }
   });
 
-  test("pgai plan --project main-db resolves the alias via projects_list", async () => {
+  test("pgai joe plan --project main-db resolves the alias via projects_list", async () => {
     const api = startFakeApi();
     try {
       const r = await runCliAsync(
-        ["plan", "select 1", "--project", "main-db"],
+        ["joe", "plan", "select 1", "--project", "main-db"],
         isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -190,15 +201,15 @@ describe("CLI Joe command surface", () => {
     }
   });
 
-  test("optimize loop: plan then exec reuse the same session on one project", async () => {
+  test("optimize loop: joe plan then joe exec reuse the same session on one project", async () => {
     const api = startFakeApi();
     const env = isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl });
     try {
       // First command starts a fresh session; the server hands back session 88.
-      const first = await runCliAsync(["plan", "select 1", "--project", "12", "--new-session"], env);
+      const first = await runCliAsync(["joe", "plan", "select 1", "--project", "12", "--new-session"], env);
       expect(first.status).toBe(0);
       // Second command auto-reuses the stored session (88) on the same project.
-      const second = await runCliAsync(["exec", "create index on users (email)", "--project", "12"], env);
+      const second = await runCliAsync(["joe", "exec", "create index on users (email)", "--project", "12"], env);
       expect(second.status).toBe(0);
       expect(second.stdout).toContain("CREATE INDEX");
 
@@ -215,21 +226,21 @@ describe("CLI Joe command surface", () => {
     }
   });
 
-  test("cold clone exceeds the budget -> resume handle (exit 0), then pgai result", async () => {
+  test("cold clone exceeds the budget -> resume handle (exit 0), then pgai joe result", async () => {
     const api = startFakeApi();
     const env = isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl });
     try {
       // project 77 (COLD) stays `running`; --budget 0 forces immediate resume.
-      const r = await runCliAsync(["plan", "select 1", "--project", "77", "--budget", "0"], env);
+      const r = await runCliAsync(["joe", "plan", "select 1", "--project", "77", "--budget", "0"], env);
       expect(r.status).toBe(0);
       expect(r.stdout).toContain("resume:");
-      expect(r.stdout).toMatch(/pgai result \d+/);
+      expect(r.stdout).toMatch(/pgai joe result \d+/);
 
-      const match = r.stdout.match(/pgai result (\d+)/);
+      const match = r.stdout.match(/pgai joe result (\d+)/);
       const commandId = match ? match[1] : "";
       expect(commandId).not.toBe("");
 
-      const resumed = await runCliAsync(["result", commandId], env);
+      const resumed = await runCliAsync(["joe", "result", commandId], env);
       expect(resumed.status).toBe(0);
       expect(resumed.stdout).toContain("Seq Scan on users");
     } finally {
@@ -241,7 +252,7 @@ describe("CLI Joe command surface", () => {
     const api = startFakeApi();
     try {
       const r = await runCliAsync(
-        ["plan", "select 1", "--project", "999"],
+        ["joe", "plan", "select 1", "--project", "999"],
         isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(1);
@@ -251,11 +262,11 @@ describe("CLI Joe command surface", () => {
     }
   });
 
-  test("terminate requires a numeric pid and maps args.pid", async () => {
+  test("joe terminate requires a numeric pid and maps args.pid", async () => {
     const api = startFakeApi();
     try {
       const r = await runCliAsync(
-        ["terminate", "4711", "--project", "12"],
+        ["joe", "terminate", "4711", "--project", "12"],
         isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -268,11 +279,11 @@ describe("CLI Joe command surface", () => {
     }
   });
 
-  test("describe maps args.object (and --variant)", async () => {
+  test("joe describe maps args.object (and --variant)", async () => {
     const api = startFakeApi();
     try {
       const r = await runCliAsync(
-        ["describe", "users", "--project", "12", "--variant", "\\d+"],
+        ["joe", "describe", "users", "--project", "12", "--variant", "\\d+"],
         isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -285,13 +296,13 @@ describe("CLI Joe command surface", () => {
   });
 
   test("missing --project fails fast", () => {
-    const r = runCli(["plan", "select 1"], isolatedEnv({ PGAI_API_KEY: "k" }));
+    const r = runCli(["joe", "plan", "select 1"], isolatedEnv({ PGAI_API_KEY: "k" }));
     expect(r.status).toBe(1);
     expect(`${r.stdout}\n${r.stderr}`).toContain("Project is required");
   });
 
   test("missing API key fails fast", () => {
-    const r = runCli(["plan", "select 1", "--project", "12"], isolatedEnv());
+    const r = runCli(["joe", "plan", "select 1", "--project", "12"], isolatedEnv());
     expect(r.status).toBe(1);
     expect(`${r.stdout}\n${r.stderr}`).toContain("API key is required");
   });

package/test/util.test.ts

@@ -41,4 +41,39 @@ describe("formatHttpError", () => {
     expect(msg.indexOf("Invalid token")).toBeGreaterThan(-1);
     expect(msg.indexOf("Invalid token")).toBeLessThan(msg.indexOf("Run 'postgresai auth'"));
   });
+
+  // PostgREST v9's PTxyz custom-status convention carries the RPC's user-facing
+  // `message` in the HTTP reason phrase (statusText); the JSON body holds only
+  // `hint`/`details` (no `message`/`code`). The formatter must surface the
+  // reason phrase as the headline instead of a hardcoded generic label, and
+  // still show the `details` (plural) line.
+  test("surfaces the PostgREST PTxyz reason-phrase message, not a generic label", () => {
+    const msg = formatHttpError(
+      "Failed to submit plan command",
+      403,
+      '{"hint":null,"details":"The LLM-facing Joe surface is gated on the organization\'s ai_enabled setting."}',
+      "AI features disabled for this org — enable in AI Assistant Settings"
+    );
+
+    expect(msg).toContain("HTTP 403");
+    expect(msg).toContain("AI features disabled for this org — enable in AI Assistant Settings");
+    // the real reason must not be masked by the hardcoded generic label
+    expect(msg).not.toContain("Forbidden - access denied");
+    // the supplementary `details` (plural) line is still shown
+    expect(msg).toContain("gated on the organization's ai_enabled setting");
+    // and we never dump the raw JSON object
+    expect(msg).not.toContain('"hint"');
+  });
+
+  test("prefers a JSON body `message` over the reason phrase when both exist", () => {
+    const msg = formatHttpError("op", 400, '{"message":"real message","details":"more"}', "Bad Request");
+    expect(msg).toContain("real message");
+    expect(msg).toContain("more");
+  });
+
+  test("falls back to the generic label for a standard (non-custom) reason phrase", () => {
+    // a bare standard reason phrase must not replace the friendlier generic label
+    const msg = formatHttpError("op", 403, undefined, "Forbidden");
+    expect(msg).toContain("Forbidden - access denied");
+  });
 });