postgresai 0.16.0-dev.0 → 0.16.0-dev.10

package/bin/postgres-ai.ts

@@ -13,6 +13,32 @@ import { Client } from "pg";
 import { startMcpServer } from "../lib/mcp-server";
 import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue, createIssue, updateIssue, updateIssueComment, fetchActionItem, fetchActionItems, createActionItem, updateActionItem, type ConfigChange } from "../lib/issues";
 import { fetchReports, fetchAllReports, fetchReportFiles, fetchReportFileData, renderMarkdownForTerminal, parseFlexibleDate } from "../lib/reports";
+import {
+  executeJoeCommand,
+  listProjects,
+  getCommandResult,
+  getCommandStatus,
+  formatJoeResult,
+  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";
@@ -2443,9 +2469,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 +2518,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 +3207,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 +3233,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 +3267,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,
@@ -5312,6 +5402,695 @@ function tryParseJson(s: string): unknown {
   try { return JSON.parse(s); } catch { return s; }
 }
 
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+
+interface JoeCliOpts {
+  project?: string;
+  session?: string;
+  newSession?: boolean;
+  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 {
+  // The expiry hint reports the ACTUAL effective budget (--budget when given,
+  // the default otherwise) — not a hardcoded DEFAULT_BUDGET_MS.
+  const effectiveBudgetMs =
+    typeof budgetMs === "number" && Number.isFinite(budgetMs) ? budgetMs : DEFAULT_BUDGET_MS;
+  const budgetSeconds = Math.round(effectiveBudgetMs / 1000);
+  // One-shot budget reached before a terminal state — hand back a resume handle.
+  // This is expected (a cold clone), NOT a failure: exit 0.
+  if (outcome.budgetExpired) {
+    if (json) {
+      console.log(
+        JSON.stringify(
+          {
+            command_id: outcome.commandId,
+            status: outcome.status,
+            session_id: outcome.sessionId,
+            budget_expired: true,
+            resume: `pgai joe result ${outcome.commandId}`,
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(
+        `submitted ${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);
+      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}`
+  );
+  process.exitCode = 1;
+}
+
+async function runJoeCli(
+  command: JoeCommand,
+  sql: string | null,
+  args: Record<string, unknown> | null,
+  opts: JoeCliOpts
+): Promise<void> {
+  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 projectRef = (opts.project ?? cfg.defaultProject ?? "").toString().trim();
+    if (!projectRef) {
+      console.error("Project is required. Pass --project <id|alias>.");
+      process.exitCode = 1;
+      return;
+    }
+    const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+    const budgetMs =
+      typeof opts.budget === "number" && !Number.isNaN(opts.budget) ? opts.budget * 1000 : undefined;
+
+    const outcome = await executeJoeCommand({
+      apiKey,
+      apiBaseUrl,
+      command,
+      project: projectRef,
+      sql,
+      args,
+      session: opts.session ?? null,
+      newSession: !!opts.newSession,
+      orgId: cfg.orgId ?? undefined,
+      budgetMs,
+      debug: !!opts.debug,
+    });
+
+    printJoeOutcome(command, outcome, !!opts.json, budgetMs);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+  }
+}
+
+/** Attach the shared Joe options (--project / --session / --new-session / --budget). */
+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("--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");
+
+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);
+});
+
+withJoeOptions(
+  joe
+    .command("explain <sql>")
+    .description("EXPLAIN ANALYZE a query (EXECUTES on the hardened, ephemeral clone)")
+).action(async (sql: string, opts: JoeCliOpts) => {
+  await runJoeCli("explain", sql, null, opts);
+});
+
+withJoeOptions(
+  joe
+    .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);
+});
+
+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);
+});
+
+withJoeOptions(
+  joe
+    .command("activity")
+    .description("running-activity snapshot (pg_stat_activity; query text redacted)")
+).action(async (opts: JoeCliOpts) => {
+  await runJoeCli("activity", null, null, opts);
+});
+
+withJoeOptions(
+  joe
+    .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);
+});
+
+withJoeOptions(
+  joe
+    .command("reset")
+    .description("reset/recreate the session's thin clone")
+).action(async (opts: JoeCliOpts) => {
+  await runJoeCli("reset", null, null, 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 (object: string, opts: JoeCliOpts) => {
+  const args: Record<string, unknown> = { object };
+  if (opts.variant) args.variant = opts.variant;
+  await runJoeCli("describe", null, args, 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>`.
+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: string, 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 status = await getCommandStatus({ apiKey, apiBaseUrl, commandId, debug: !!opts.debug });
+      if (opts.json) {
+        console.log(JSON.stringify(status, null, 2));
+      } else {
+        console.log(`command ${status.command_id} · ${status.status}${status.error ? ` · ${status.error}` : ""}`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(message);
+      process.exitCode = 1;
+    }
+  });
+
+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)")
+  .option("--debug", "enable debug output")
+  .option("--json", "output raw JSON")
+  .action(async (commandId: string, 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 result = await getCommandResult({ apiKey, apiBaseUrl, commandId, 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;
+      } else {
+        console.log(`command ${result.command_id} · ${result.status}`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(message);
+      process.exitCode = 1;
+    }
+  });
+
+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");
 
@@ -5488,3 +6267,7 @@ if (import.meta.main) {
 // same functions used by the `mon` commands).
 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 };