postgresai 0.16.0-dev.10 → 0.16.0-dev.11

package/bin/postgres-ai.ts

@@ -16,29 +16,13 @@ import { fetchReports, fetchAllReports, fetchReportFiles, fetchReportFileData, r
 import {
   executeJoeCommand,
   listProjects,
-  getCommandResult,
-  getCommandStatus,
-  formatJoeResult,
+  getCommandOutput,
+  formatJoeOutput,
   formatProjectsTable,
   DEFAULT_BUDGET_MS,
   type JoeCommand,
   type ExecuteJoeOutcome,
 } from "../lib/joe";
-import {
-  resolveDblabInstanceId,
-  createClone,
-  listClones,
-  getClone,
-  resetClone,
-  destroyClone,
-  listBranches,
-  createBranch,
-  deleteBranch,
-  branchLog,
-  listSnapshots,
-  createSnapshot,
-  destroySnapshot,
-} from "../lib/dblab";
 import { resolveBaseUrls } from "../lib/util";
 import { registerAasCollection, parseVcpus } from "../lib/aas-onboard";
 import { uploadFile, downloadFile, buildMarkdownLink, uploadAttachments, appendAttachmentsToContent } from "../lib/storage";
@@ -361,12 +345,18 @@ function prepareUploadConfig(
       console.error("Tip: run 'postgresai auth' or pass --api-key / set PGAI_API_KEY");
       return null; // Signal to exit
     }
-    // No credentials and upload not explicitly requested: fall back to
-    // local-only mode, but say so prominently — skipping the upload silently
-    // hides the fact that results never reach the Console.
-    console.error("Notice: no API key configured — results will NOT be uploaded to PostgresAI.");
-    console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
-    console.error("        To run locally without this notice, pass --no-upload.");
+    if (opts.markdown) {
+      console.error("Notice: no API key configured — regular report upload is disabled.");
+      console.error("        The full report JSON will still be sent to the PostgresAI API for markdown conversion.");
+      console.error("        To avoid sending report data, replace --markdown with --no-upload and --json or --output.");
+    } else {
+      // No credentials and upload not explicitly requested: fall back to
+      // local-only mode, but say so prominently — skipping the upload silently
+      // hides the fact that results never reach the Console.
+      console.error("Notice: no API key configured — results will NOT be uploaded to PostgresAI.");
+      console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
+      console.error("        To run locally without this notice, pass --no-upload.");
+    }
     return undefined; // Skip upload, run checks locally
   }
 
@@ -2022,7 +2012,7 @@ program
     "project name or ID for remote upload (used with --upload; defaults to config defaultProject; auto-generated on first run)"
   )
   .option("--json", "output JSON to stdout")
-  .option("--markdown", "output markdown to stdout")
+  .option("--markdown", "output markdown via PostgresAI API (transmits the full report JSON)")
   .addHelpText(
     "after",
     [
@@ -2036,7 +2026,7 @@ program
       "  postgresai checkup postgresql://user:pass@host:5432/db --check-id H002",
       "  postgresai checkup postgresql://user:pass@host:5432/db --output ./reports",
       "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --json",
-      "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --markdown",
+      "  postgresai checkup postgresql://user:pass@host:5432/db --markdown",
     ].join("\n")
   )
   .action(async (checkIdOrConn: string | undefined, connArg: string | undefined, opts: CheckupOptions, cmd: Command) => {
@@ -2086,9 +2076,14 @@ program
       process.exitCode = 1;
       return;
     }
-    // Note: --json, --markdown and --upload/--no-upload are independent flags.
-    // Use --no-upload to explicitly disable upload when using --json or --markdown.
     const uploadExplicitlyDisabled = opts.upload === false;
+    if (uploadExplicitlyDisabled && shouldConvertMarkdown) {
+      console.error("Error: --no-upload and --markdown are mutually exclusive");
+      console.error("Markdown conversion is performed by the PostgresAI API and transmits the full report JSON.");
+      console.error("Drop --no-upload to allow transmission, or use --json or --output for local-only output.");
+      process.exitCode = 1;
+      return;
+    }
     let shouldUpload = !uploadExplicitlyDisabled;
 
     // Preflight: validate/create output directory BEFORE connecting / running checks.
@@ -2334,7 +2329,9 @@ program
 
         console.log('\nFor details:');
         console.log('  --json          Output JSON');
-        console.log('  --markdown      Output markdown');
+        if (!uploadExplicitlyDisabled) {
+          console.log('  --markdown      Output markdown via PostgresAI API');
+        }
         console.log('  --output <dir>  Save to directory');
       }
     } catch (error) {
@@ -3957,13 +3954,9 @@ targets
 // Authentication and API key management
 const auth = program.command("auth").description("authentication and API key management");
 
-auth
-  .command("login", { isDefault: true })
-  .description("authenticate via browser (OAuth) or store API key directly")
-  .option("--set-key <key>", "store API key directly without OAuth flow")
-  .option("--port <port>", "local callback server port (default: random)", parseInt)
-  .option("--debug", "enable debug output")
-  .action(async (opts: { setKey?: string; port?: number; debug?: boolean }) => {
+type AuthLoginOptions = { setKey?: string; port?: number; debug?: boolean };
+
+async function runAuthLogin(opts: AuthLoginOptions) {
     // If --set-key is provided, store it directly without OAuth
     if (opts.setKey) {
       const trimmedKey = opts.setKey.trim();
@@ -4217,7 +4210,21 @@ auth
       console.error(`Authentication error: ${message}`);
       process.exit(1);
     }
-  });
+}
+
+function configureLoginCommand(command: Command): Command {
+  return command
+    .description("authenticate via browser (OAuth) or store API key directly")
+    .option("--set-key <key>", "store API key directly without OAuth flow")
+    .option("--port <port>", "local callback server port (default: random)", parseInt)
+    .option("--debug", "enable debug output");
+}
+
+configureLoginCommand(auth.command("login", { isDefault: true }))
+  .action(runAuthLogin);
+
+configureLoginCommand(program.command("login"))
+  .action(runAuthLogin);
 
 auth
   .command("show-key")
@@ -5403,58 +5410,24 @@ function tryParseJson(s: string): unknown {
 }
 
 // ---------------------------------------------------------------------------
-// Joe API v2 command surface (SPEC §6). Every verb is a client-side
-// submit-then-poll one-shot over `v1.joe_command_submit`; `--project` accepts a
-// numeric id OR an alias/name (id-or-alias resolution). `plan` is plan-only
-// (EXPLAIN, no execution); `explain` (EXPLAIN ANALYZE) and `exec` execute on the
-// hardened, ephemeral DBLab clone. The backend rpcs are mocked in tests.
+// Joe command surface (Joe API v2 CLI v1, issue #438). Every verb builds the
+// RAW command text Joe's /webui/command dispatches (`plan <sql>`, `\d users`),
+// runs it via the synchronous `v1.joe_command_run`, and polls
+// `v1.joe_command_output` until `ok`/`error` within the one-shot budget.
+// `--project` accepts a numeric id OR an alias/name/label. The backend rpcs
+// are mocked in tests.
 // ---------------------------------------------------------------------------
 
 interface JoeCliOpts {
   project?: string;
-  session?: string;
-  newSession?: boolean;
+  instanceId?: string;
   budget?: number;
-  query?: string;
   variant?: string;
   debug?: boolean;
   json?: boolean;
 }
 
-// ============================================================================
-// DBLab companion command surface (Joe API v2 · SPEC §8)
-//
-// `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. The DESTRUCTIVE verbs — the HTTP DELETEs: clone
-// destroy, branch delete, snapshot destroy — require the `joe:admin` token
-// scope (user-approved tightening, !612); clone reset is a POST and is NOT
-// gated. Read/list/create verbs stay at org-token + project-allowlist level.
-// All enforced backend-side — a PT403 surfaces here as an HTTP 403.
-//
-// NOTE: kept in its own region and its own lib (cli/lib/dblab.ts) so it does not
-// collide with the parallel Joe-commands work.
-// ============================================================================
-
-interface DblabCmdOpts {
-  project?: string;
-  debug?: boolean;
-  json?: boolean;
-}
-
-function inferCommandFromResult(r: { command?: JoeCommand; plan_json?: unknown; plan_text?: string | null; row_count?: number | null; result_rows?: unknown[] | null; hypo_plan?: unknown; hypo_used?: boolean | null; terminated?: boolean | null; pid?: number | null; reset?: boolean | null; snapshot?: unknown }): JoeCommand | null {
-  if (r.command) return r.command;
-  if (r.plan_text !== undefined || r.plan_json !== undefined) return "plan";
-  if (r.row_count !== undefined || r.result_rows !== undefined) return "exec";
-  if (r.hypo_used !== undefined) return "hypo";
-  if (r.terminated !== undefined) return "terminate";
-  if (r.reset !== undefined) return "reset";
-  if (r.snapshot !== undefined) return "activity";
-  return null;
-}
-
-function printJoeOutcome(command: JoeCommand, outcome: ExecuteJoeOutcome, json: boolean, budgetMs?: number): void {
+function printJoeOutcome(outcome: ExecuteJoeOutcome, json: boolean, budgetMs?: number): void {
   // The expiry hint reports the ACTUAL effective budget (--budget when given,
   // the default otherwise) — not a hardcoded DEFAULT_BUDGET_MS.
   const effectiveBudgetMs =
@@ -5469,7 +5442,6 @@ function printJoeOutcome(command: JoeCommand, outcome: ExecuteJoeOutcome, json:
           {
             command_id: outcome.commandId,
             status: outcome.status,
-            session_id: outcome.sessionId,
             budget_expired: true,
             resume: `pgai joe result ${outcome.commandId}`,
           },
@@ -5479,43 +5451,37 @@ function printJoeOutcome(command: JoeCommand, outcome: ExecuteJoeOutcome, json:
       );
     } else {
       console.log(
-        `submitted ${outcome.commandId} · ${outcome.status} · budget ${budgetSeconds}s reached — resume:  pgai joe result ${outcome.commandId}`
+        `started ${outcome.commandId} · ${outcome.status} · budget ${budgetSeconds}s reached — resume:  pgai joe result ${outcome.commandId}`
       );
     }
     return;
   }
 
-  const result = outcome.result;
-  if (outcome.status === "done" && result) {
-    if (json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`submitted ${outcome.commandId} · done`);
-      const body = formatJoeResult(command, result);
+  const output = outcome.output;
+  if (outcome.status === "ok") {
+    if (!output) {
+      console.error(`command ${outcome.commandId} ok but output is empty`);
+      process.exitCode = 1;
+      return;
+    }
+    if (json) console.log(JSON.stringify(output, null, 2));
+    else {
+      console.log(`command ${outcome.commandId} · ok`);
+      const body = formatJoeOutput(output);
       if (body) console.log(body);
     }
     return;
   }
 
-  if (outcome.status === "error") {
-    const msg = result?.error ?? "command failed";
-    console.error(`command ${outcome.commandId} error: ${msg}`);
-    process.exitCode = 1;
-    return;
-  }
-
-  // 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 joe result ${outcome.commandId}`
-  );
+  // Terminal error.
+  if (json && output) console.log(JSON.stringify(output, null, 2));
+  console.error(`command ${outcome.commandId} error: ${output?.error ?? "command failed"}`);
   process.exitCode = 1;
 }
 
 async function runJoeCli(
   command: JoeCommand,
-  sql: string | null,
-  args: Record<string, unknown> | null,
+  arg: string | null,
   opts: JoeCliOpts
 ): Promise<void> {
   try {
@@ -5528,30 +5494,33 @@ async function runJoeCli(
       return;
     }
     const projectRef = (opts.project ?? cfg.defaultProject ?? "").toString().trim();
-    if (!projectRef) {
-      console.error("Project is required. Pass --project <id|alias>.");
+    const instanceRef = (opts.instanceId ?? "").toString().trim();
+    if (!projectRef && !instanceRef) {
+      console.error(
+        "Specify --instance-id <id> (or --project <id|alias> once projects_list is available)."
+      );
       process.exitCode = 1;
       return;
     }
     const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
-    const budgetMs =
-      typeof opts.budget === "number" && !Number.isNaN(opts.budget) ? opts.budget * 1000 : undefined;
+    if (typeof opts.budget === "number" && (!Number.isFinite(opts.budget) || opts.budget < 0)) {
+      throw new Error("--budget must be a non-negative number of seconds");
+    }
+    const budgetMs = typeof opts.budget === "number" ? opts.budget * 1000 : undefined;
 
     const outcome = await executeJoeCommand({
       apiKey,
       apiBaseUrl,
       command,
-      project: projectRef,
-      sql,
-      args,
-      session: opts.session ?? null,
-      newSession: !!opts.newSession,
+      project: projectRef || undefined,
+      instanceId: instanceRef || undefined,
+      input: { arg, variant: opts.variant ?? null },
       orgId: cfg.orgId ?? undefined,
       budgetMs,
       debug: !!opts.debug,
     });
 
-    printJoeOutcome(command, outcome, !!opts.json, budgetMs);
+    printJoeOutcome(outcome, !!opts.json, budgetMs);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     console.error(message);
@@ -5559,40 +5528,37 @@ async function runJoeCli(
   }
 }
 
-/** Attach the shared Joe options (--project / --session / --new-session / --budget). */
+/** Attach the shared Joe options (--instance-id / --project / --budget / --debug / --json). */
 function withJoeOptions(cmd: import("commander").Command): import("commander").Command {
   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(
+      "--instance-id <id>",
+      "target the Joe instance id directly (skips --project resolution; the v1 path while projects_list is unavailable)"
+    )
+    .option("--project <id|alias>", "target project by numeric id OR alias/name (requires projects_list)")
+    .option("--budget <seconds>", "one-shot poll budget in seconds (default 25)", (v) => parseFloat(v))
     .option("--debug", "enable debug output")
     .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");
+  .description("Joe — plan/EXPLAIN/exec queries on ephemeral DBLab clones");
 
 withJoeOptions(
   joe
     .command("plan <sql>")
     .description("plan a query (EXPLAIN, plan-only — no execution; the fast/safe default)")
 ).action(async (sql: string, opts: JoeCliOpts) => {
-  await runJoeCli("plan", sql, null, opts);
+  await runJoeCli("plan", sql, opts);
 });
 
 withJoeOptions(
   joe
     .command("explain <sql>")
-    .description("EXPLAIN ANALYZE a query (EXECUTES on the hardened, ephemeral clone)")
+    .description("EXPLAIN + EXPLAIN ANALYZE a query (EXECUTES on the ephemeral clone)")
 ).action(async (sql: string, opts: JoeCliOpts) => {
-  await runJoeCli("explain", sql, null, opts);
+  await runJoeCli("explain", sql, opts);
 });
 
 withJoeOptions(
@@ -5600,24 +5566,23 @@ withJoeOptions(
     .command("exec <sql>")
     .description("run arbitrary DDL/DML on the clone (e.g. create index, analyze)")
 ).action(async (sql: string, opts: JoeCliOpts) => {
-  await runJoeCli("exec", sql, null, opts);
+  await runJoeCli("exec", sql, 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: string, opts: JoeCliOpts) => {
-  await runJoeCli("hypo", indexSql, { query: opts.query }, opts);
+    .command("hypo <args>")
+    .description("HypoPG hypothetical indexes (e.g. `hypo create index on users (email)`, `hypo desc`, `hypo reset`)")
+).action(async (args: string, opts: JoeCliOpts) => {
+  await runJoeCli("hypo", args, opts);
 });
 
 withJoeOptions(
   joe
     .command("activity")
-    .description("running-activity snapshot (pg_stat_activity; query text redacted)")
+    .description("running-activity snapshot (pg_stat_activity) on the clone")
 ).action(async (opts: JoeCliOpts) => {
-  await runJoeCli("activity", null, null, opts);
+  await runJoeCli("activity", null, opts);
 });
 
 withJoeOptions(
@@ -5625,18 +5590,9 @@ withJoeOptions(
     .command("terminate <pid>")
     .description("pg_terminate_backend(pid) on the clone")
 ).action(async (pid: string, opts: JoeCliOpts) => {
-  // A pid must be a bare non-negative integer. parseInt() silently accepts
-  // trailing garbage ("12x"→12), a sign ("-5"→-5), decimals ("1.5"→1) and hex
-  // ("0x10"→0) — any of which would submit a terminate against the WRONG
-  // backend pid. Require a fully-numeric token so a mistyped pid is a clean,
-  // typed rejection that never reaches the submit rpc.
-  const pidStr = (pid ?? "").trim();
-  if (!/^[0-9]+$/.test(pidStr)) {
-    console.error("pid must be a number");
-    process.exitCode = 1;
-    return;
-  }
-  await runJoeCli("terminate", null, { pid: parseInt(pidStr, 10) }, opts);
+  // The bare-positive-integer pid guard lives in buildJoeCommandText, which
+  // runs before any network call — a mistyped pid never reaches an rpc.
+  await runJoeCli("terminate", pid, opts);
 });
 
 withJoeOptions(
@@ -5644,7 +5600,7 @@ withJoeOptions(
     .command("reset")
     .description("reset/recreate the session's thin clone")
 ).action(async (opts: JoeCliOpts) => {
-  await runJoeCli("reset", null, null, opts);
+  await runJoeCli("reset", null, opts);
 });
 
 withJoeOptions(
@@ -5653,138 +5609,14 @@ withJoeOptions(
     .description("\\d-family schema/relation/index metadata")
     .option("--variant <variant>", "\\d-family variant (e.g. \\d+, \\di, \\dt)")
 ).action(async (object: string, opts: JoeCliOpts) => {
-  const args: Record<string, unknown> = { object };
-  if (opts.variant) args.variant = opts.variant;
-  await runJoeCli("describe", null, args, opts);
+  await runJoeCli("describe", object, opts);
 });
 
-// history search is roadmapped for M1b; the search backend is not deployed yet.
-// Ship a recognized subcommand so the documented `pgai joe history …` example
-// degrades cleanly (an informative "not yet available" line + exit 1) instead of
-// Commander's generic "unknown command 'history'". Wire it to the rpc when M1b lands.
-withJoeOptions(
-  joe
-    .command("history <terms>")
-    .description("search prior Joe analyses, metadata-only (M1b — not yet available)")
-).action(async (_terms: string, _opts: JoeCliOpts) => {
-  console.error(
-    "Joe history search is not available yet — it is planned for M1b. " +
-      "No history-search backend is deployed; this command is a placeholder until then.",
-  );
-  process.exitCode = 1;
-});
-
-// Org-level discovery — a general postgresai command, NOT a Joe endpoint (SPEC §6).
-program
-  .command("projects")
-  .description("list the org's projects (shows which have Joe ready) — org-level, not a Joe endpoint")
-  .option("--debug", "enable debug output")
-  .option("--json", "output raw JSON")
-  .action(async (opts: { debug?: boolean; json?: boolean }) => {
-    try {
-      const rootOpts = program.opts<CliOptions>();
-      const cfg = config.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 } = resolveBaseUrls(rootOpts, cfg);
-      const projects = await listProjects({
-        apiKey,
-        apiBaseUrl,
-        orgId: cfg.orgId ?? undefined,
-        debug: !!opts.debug,
-      });
-      if (opts.json) {
-        console.log(JSON.stringify(projects, null, 2));
-      } else {
-        console.log(formatProjectsTable(projects));
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      console.error(message);
-      process.exitCode = 1;
-    }
-  });
-
-/**
- * Resolve the shared inputs every DBLab verb needs: the api key, the api base
- * url, and the project's single DBLab `instance_id`. Throws (caught by each
- * action → exit 1) when the api key or `--project` is missing, or when no DBLab
- * instance can be resolved for the project.
- */
-async function resolveDblabTarget(
-  project: string | undefined,
-  debug: boolean
-): Promise<{ apiKey: string; apiBaseUrl: string; orgId?: number; instanceId: string }> {
-  const rootOpts = program.opts<CliOptions>();
-  const cfg = config.readConfig();
-  const { apiKey } = getConfig(rootOpts);
-  if (!apiKey) {
-    throw new Error("API key is required. Run 'pgai auth' first or set --api-key.");
-  }
-  const ref = (project ?? "").trim();
-  if (!ref) {
-    throw new Error("--project <id|alias> is required");
-  }
-  const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
-  const orgId = cfg.orgId ?? undefined;
-  const instanceId = await resolveDblabInstanceId({ apiKey, apiBaseUrl, project: ref, orgId, debug });
-  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 = dblab.command("clone").description("DBLab thin-clone management (proxies the Platform DBLab API)");
-
-clone
-  .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: DblabCmdOpts & { branch?: string; snapshot?: string; id?: string; dbUser?: string; dbPassword?: string; protected?: boolean }) => {
-    try {
-      const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
-      const result = await createClone({
-        apiKey, apiBaseUrl, instanceId,
-        cloneId: opts.id,
-        branch: opts.branch,
-        snapshotId: opts.snapshot,
-        dbUser: opts.dbUser,
-        dbPassword: opts.dbPassword,
-        isProtected: !!opts.protected,
-        debug: !!opts.debug,
-      });
-      printResult(result, opts.json);
-    } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-    }
-  });
-
-// Resume / inspect a previously submitted command by id. Part of the `joe` group
-// (`pgai joe status <commandId>`) — distinct from `pgai dblab clone status <cloneId>`.
+// Resume / inspect a previously started command by id (the budget-expiry
+// resume handle printed by the one-shot verbs).
 joe
-  .command("status <commandId>")
-  .description("show a Joe command's status (metadata only)")
+  .command("result <commandId>")
+  .description("fetch a Joe command's output by id (resume a budget-expired one-shot)")
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
   .action(async (commandId: string, opts: { debug?: boolean; json?: boolean }) => {
@@ -5798,11 +5630,27 @@ joe
         return;
       }
       const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
-      const status = await getCommandStatus({ apiKey, apiBaseUrl, commandId, debug: !!opts.debug });
+      const output = await getCommandOutput({ apiKey, apiBaseUrl, commandId, debug: !!opts.debug });
       if (opts.json) {
-        console.log(JSON.stringify(status, null, 2));
+        console.log(JSON.stringify(output, null, 2));
+        // Same exit contract as the human output and the one-shot path
+        // (printJoeOutcome): only `ok` is a result — scripts consuming --json
+        // must not proceed on `pending`/`error`.
+        if (output.status !== "ok") {
+          process.exitCode = 1;
+        }
+        return;
+      }
+      if (output.status === "ok") {
+        console.log(`command ${output.command_id} · ok`);
+        const body = formatJoeOutput(output);
+        if (body) console.log(body);
+      } else if (output.status === "error") {
+        console.error(`command ${output.command_id} error: ${output.error ?? "command failed"}`);
+        process.exitCode = 1;
       } else {
-        console.log(`command ${status.command_id} · ${status.status}${status.error ? ` · ${status.error}` : ""}`);
+        console.error(`command ${output.command_id} · ${output.status} — result is not ready`);
+        process.exitCode = 1;
       }
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -5811,29 +5659,13 @@ joe
     }
   });
 
-clone
-  .command("list")
-  .description("list the project's thin clones")
-  .requiredOption("--project <id|alias>", "project id or alias")
-  .option("--debug", "enable debug output")
-  .option("--json", "output raw JSON")
-  .action(async (opts: DblabCmdOpts) => {
-    try {
-      const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
-      const result = await listClones({ apiKey, apiBaseUrl, instanceId, debug: !!opts.debug });
-      printResult(result, opts.json);
-    } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-    }
-  });
-
-joe
-  .command("result <commandId>")
-  .description("fetch a Joe command's result by id (resume a timed-out one-shot)")
+// Org-level discovery — a general postgresai command, NOT a Joe endpoint.
+program
+  .command("projects")
+  .description("list the org's projects (shows which have Joe ready) — org-level, not a Joe endpoint")
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
-  .action(async (commandId: string, opts: { debug?: boolean; json?: boolean }) => {
+  .action(async (opts: { debug?: boolean; json?: boolean }) => {
     try {
       const rootOpts = program.opts<CliOptions>();
       const cfg = config.readConfig();
@@ -5844,33 +5676,16 @@ joe
         return;
       }
       const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
-      const result = await getCommandResult({ apiKey, apiBaseUrl, commandId, debug: !!opts.debug });
+      const projects = await listProjects({
+        apiKey,
+        apiBaseUrl,
+        orgId: cfg.orgId ?? undefined,
+        debug: !!opts.debug,
+      });
       if (opts.json) {
-        console.log(JSON.stringify(result, null, 2));
-        // Same exit contract as the human output and the one-shot path
-        // (printJoeOutcome): a terminal failure is a non-result — scripts
-        // consuming --json must not proceed on it.
-        if (result.status === "error" || result.status === "timed_out") {
-          process.exitCode = 1;
-        }
-        return;
-      }
-      const inferred = inferCommandFromResult(result);
-      if (result.status === "done" && inferred) {
-        console.log(`command ${result.command_id} · done`);
-        const body = formatJoeResult(inferred, result);
-        if (body) console.log(body);
-      } else if (result.status === "error") {
-        console.error(`command ${result.command_id} error: ${result.error ?? "command failed"}`);
-        process.exitCode = 1;
-      } else if (result.status === "timed_out") {
-        // Terminal server-side timeout — a non-result. Match the one-shot path
-        // (printJoeOutcome): report and exit non-zero so `pgai joe result $id
-        // && next-step` scripts do not proceed.
-        console.error(`command ${result.command_id} timed out on the server`);
-        process.exitCode = 1;
+        console.log(JSON.stringify(projects, null, 2));
       } else {
-        console.log(`command ${result.command_id} · ${result.status}`);
+        console.log(formatProjectsTable(projects));
       }
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -5879,218 +5694,6 @@ joe
     }
   });
 
-clone
-  .command("status <cloneId>")
-  .description("show a clone's status")
-  .requiredOption("--project <id|alias>", "project id or alias")
-  .option("--debug", "enable debug output")
-  .option("--json", "output raw JSON")
-  .action(async (cloneId: string, opts: DblabCmdOpts) => {
-    try {
-      const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
-      const result = await getClone({ apiKey, apiBaseUrl, instanceId, cloneId, debug: !!opts.debug });
-      printResult(result, opts.json);
-    } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-    }
-  });
-
-clone
-  .command("reset <cloneId>")
-  .description("reset a clone to a pristine snapshot")
-  .requiredOption("--project <id|alias>", "project id or alias")
-  .option("--snapshot <id>", "snapshot id to reset to (default: latest)")
-  .option("--latest", "reset to the latest snapshot")
-  .option("--debug", "enable debug output")
-  .option("--json", "output raw JSON")
-  .action(async (cloneId: string, opts: DblabCmdOpts & { snapshot?: string; latest?: boolean }) => {
-    try {
-      const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
-      const result = await resetClone({
-        apiKey, apiBaseUrl, instanceId, cloneId,
-        snapshotId: opts.snapshot,
-        latest: opts.latest,
-        debug: !!opts.debug,
-      });
-      printResult(result ?? { reset: true, cloneId }, opts.json);
-    } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-    }
-  });
-
-clone
-  .command("destroy <cloneId>")
-  .description("destroy a clone (requires joe:admin)")
-  .requiredOption("--project <id|alias>", "project id or alias")
-  .option("--debug", "enable debug output")
-  .option("--json", "output raw JSON")
-  .action(async (cloneId: string, opts: DblabCmdOpts) => {
-    try {
-      const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
-      const result = await destroyClone({ apiKey, apiBaseUrl, instanceId, cloneId, debug: !!opts.debug });
-      printResult(result ?? { destroyed: true, cloneId }, opts.json);
-    } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-    }
-  });
-
-// ---- branch ---------------------------------------------------------------
-
-const 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: DblabCmdOpts) => {
-    try {
-      const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
-      const result = await listBranches({ apiKey, apiBaseUrl, instanceId, debug: !!opts.debug });
-      printResult(result, opts.json);
-    } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-    }
-  });
-
-branch
-  .command("create <name>")
-  .description("create a branch")
-  .requiredOption("--project <id|alias>", "project id or alias")
-  .option("--snapshot <id>", "snapshot id to base the branch on")
-  .option("--base-branch <branch>", "parent branch to fork from")
-  .option("--debug", "enable debug output")
-  .option("--json", "output raw JSON")
-  .action(async (name: string, opts: DblabCmdOpts & { snapshot?: string; baseBranch?: string }) => {
-    try {
-      const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
-      const result = await createBranch({
-        apiKey, apiBaseUrl, instanceId,
-        branchName: name,
-        baseBranch: opts.baseBranch,
-        snapshotId: opts.snapshot,
-        debug: !!opts.debug,
-      });
-      printResult(result, opts.json);
-    } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-    }
-  });
-
-branch
-  .command("delete <name>")
-  .description("delete a branch (requires joe:admin)")
-  .requiredOption("--project <id|alias>", "project id or alias")
-  .option("--debug", "enable debug output")
-  .option("--json", "output raw JSON")
-  .action(async (name: string, opts: DblabCmdOpts) => {
-    try {
-      const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
-      const result = await deleteBranch({ apiKey, apiBaseUrl, instanceId, branchName: name, debug: !!opts.debug });
-      printResult(result ?? { deleted: true, branch: name }, opts.json);
-    } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-    }
-  });
-
-branch
-  .command("log <name>")
-  .description("show a branch's snapshot log")
-  .requiredOption("--project <id|alias>", "project id or alias")
-  .option("--debug", "enable debug output")
-  .option("--json", "output raw JSON")
-  .action(async (name: string, opts: DblabCmdOpts) => {
-    try {
-      const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
-      const result = await branchLog({ apiKey, apiBaseUrl, instanceId, branchName: name, debug: !!opts.debug });
-      printResult(result, opts.json);
-    } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-    }
-  });
-
-// ---- snapshot -------------------------------------------------------------
-
-const 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: DblabCmdOpts & { branch?: string; dataset?: string }) => {
-    try {
-      const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
-      const result = await listSnapshots({
-        apiKey, apiBaseUrl, instanceId,
-        branchName: opts.branch,
-        dataset: opts.dataset,
-        debug: !!opts.debug,
-      });
-      printResult(result, opts.json);
-    } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-    }
-  });
-
-snapshot
-  .command("create")
-  .description("create a snapshot from a clone")
-  .requiredOption("--project <id|alias>", "project id or alias")
-  .requiredOption("--clone <id>", "clone id to snapshot")
-  .option("--message <message>", "snapshot message")
-  .option("--debug", "enable debug output")
-  .option("--json", "output raw JSON")
-  .action(async (opts: DblabCmdOpts & { clone?: string; message?: string }) => {
-    try {
-      const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
-      const result = await createSnapshot({
-        apiKey, apiBaseUrl, instanceId,
-        cloneId: opts.clone as string,
-        message: opts.message,
-        debug: !!opts.debug,
-      });
-      printResult(result, opts.json);
-    } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-    }
-  });
-
-snapshot
-  .command("destroy <snapshotId>")
-  .description("destroy a snapshot (requires joe:admin)")
-  .requiredOption("--project <id|alias>", "project id or alias")
-  .option("--force", "force-delete even when dependent clones exist")
-  .option("--debug", "enable debug output")
-  .option("--json", "output raw JSON")
-  .action(async (snapshotId: string, opts: DblabCmdOpts & { force?: boolean }) => {
-    try {
-      const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
-      const result = await destroySnapshot({
-        apiKey, apiBaseUrl, instanceId, snapshotId,
-        force: !!opts.force,
-        debug: !!opts.debug,
-      });
-      printResult(result ?? { destroyed: true, snapshot: snapshotId }, opts.json);
-    } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-    }
-  });
-
 // MCP server
 const mcp = program.command("mcp").description("MCP server integration");
 
@@ -6268,6 +5871,3 @@ if (import.meta.main) {
 export { refreshBundledComposeIfStale, readDeployedTag, isValidComposeYaml };
 export { registerMonitoringInstance, resolveAdoptedProject, type MonitoringRegistration };
 export { planMonitoringRegistration, type MonRegistrationPlan };
-// Joe: the `pgai joe result <id>` result-body -> command inference (unit-tested
-// table-driven; the shapes are the per-command contract matrix in CONTRACT_DECISIONS).
-export { inferCommandFromResult };