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

package/lib/joe.ts

@@ -1,23 +1,30 @@
-import * as fs from "fs";
-import * as path from "path";
-import * as crypto from "node:crypto";
-import { formatHttpError, maskSecret, normalizeBaseUrl, describeFetchError, redactSecretsForLog } from "./util";
-import * as config from "./config";
+import {
+  DEFAULT_HTTP_REQUEST_TIMEOUT_MS,
+  HttpRequestTimeoutError,
+  HttpStatusError,
+  formatHttpError,
+  isRetryableHttpStatus,
+  maskSecret,
+  normalizeBaseUrl,
+  describeFetchError,
+  isFetchTimeout,
+  redactSecretsForLog,
+  requestTimeoutSignal,
+} from "./util";
 
 /**
- * Joe API v2 client (`postgres-ai` CLI / MCP surface).
+ * Joe API v2 client (`postgres-ai` CLI surface) — synchronous contract.
  *
- * Every Joe command is a thin wrapper over the platform rpc `v1.joe_command_submit`
- * (with the command's fixed `command`) plus a *client-side* status/result poll — there
- * is no DB-side sync wrapper (a single PostgREST transaction cannot both submit a
- * command and observe Joe's cross-connection callback). See SPEC §1/§5/§6.
- *
- * The backend rpcs (`joe_command_submit` / `joe_command_status` / `joe_command_result`
- * and the org-level projects listing) do not exist yet — this module is written against
- * the documented contract and exercised entirely with mocked fetch responses.
+ * Every Joe verb is a thin raw-text builder over the platform rpc
+ * `v1.joe_command_run(instance_id, command)`: the command text is sent RAW
+ * (exactly what a console user could type at Joe — `plan select …`,
+ * `exec create index …`, `\d users`), Joe dispatches the verb itself, and the
+ * CLI polls `v1.joe_command_output(command_id)` until the status is terminal
+ * (`ok`/`error`). No queue, no session store, no idempotency keys — a fresh
+ * Joe session per run (Issue #438, supersedes the async !346 surface).
  */
 
-/** The Joe command set (SPEC §5/§6 + the per-command contract matrix). */
+/** The Joe verb set (mirrors Joe's own dispatcher; `describe` = the \d family). */
 export const JOE_COMMANDS = [
   "plan",
   "explain",
@@ -31,99 +38,52 @@ export const JOE_COMMANDS = [
 
 export type JoeCommand = (typeof JOE_COMMANDS)[number];
 
-/** Terminal + non-terminal command lifecycle states returned by the platform. */
-export type JoeStatus = "queued" | "running" | "done" | "error" | "timed_out";
-
-const TERMINAL_STATES: ReadonlySet<JoeStatus> = new Set<JoeStatus>([
-  "done",
-  "error",
-  "timed_out",
-]);
-
-/** Commands whose result reaches the caller's LLM — gated on the org `ai_enabled`. */
-export const AI_ENABLED_COMMANDS: ReadonlySet<JoeCommand> = new Set<JoeCommand>([
-  "plan",
-  "explain",
-  "exec",
-  "hypo",
-  "activity",
-  "describe",
-]);
+/** Output lifecycle: `pending` while Joe has not posted, then `ok`/`error`. */
+export type JoeOutputStatus = "pending" | "ok" | "error";
 
-/** Commands that execute against the disposable clone (at-most-once posture). */
-const EXECUTING_COMMANDS: ReadonlySet<JoeCommand> = new Set<JoeCommand>([
-  "exec",
-  "explain",
-]);
-
-/** Default one-shot poll budget (SPEC §6: ≤ 25 s, then resume by handle). */
+/** Default one-shot poll budget (≤ 25 s, then resume by command id). */
 export const DEFAULT_BUDGET_MS = 25_000;
 const DEFAULT_POLL_INTERVAL_MS = 800;
 
 // ---------------------------------------------------------------------------
-// Response shapes (documented contract — mocked in tests)
+// Response shapes (the joe_command_output contract — mocked in tests)
 // ---------------------------------------------------------------------------
 
-export interface JoeSubmitResponse {
-  command_id: string;
-  session_id: string | null;
-  status: JoeStatus;
-}
-
-export interface JoeStatusResponse {
-  command_id: string;
-  status: JoeStatus;
-  enqueued_at?: string | null;
-  started_at?: string | null;
-  finished_at?: string | null;
-  error?: string | null;
-}
-
 /**
- * Command-appropriate result body (SPEC §1 + per-command contract matrix Part B).
- * A single interface is used with per-command optional keys; only the keys for the
- * submitted command are populated.
+ * The FULL raw result row `v1.joe_command_output` returns once Joe has posted.
+ * While `status` is `pending` only `command_id`/`status`/`created_at` are
+ * present. `plan_json` and `plan_execution_json` arrive structured — the rpc
+ * unwraps both from their stored jsonb-string form.
  */
-export interface JoeCommandResult {
+export interface JoeCommandOutput {
   command_id: string;
-  command?: JoeCommand;
-  status: JoeStatus;
-  error: string | null;
-  // plan / explain
+  status: JoeOutputStatus;
+  created_at?: string | null;
+  command?: string | null;
+  query?: string | null;
   queryid?: string | null;
-  plan_fingerprint?: string | null;
+  response?: string | null;
   plan_text?: string | null;
   plan_json?: unknown;
-  // exec
-  row_count?: number | null;
-  result_rows?: unknown[] | null;
-  notices?: string[] | null;
-  // hypo
-  hypo_plan?: unknown;
-  hypo_used?: boolean | null;
-  // activity / describe
-  snapshot?: unknown;
-  // terminate
-  terminated?: boolean | null;
-  pid?: number | null;
-  // reset
-  reset?: boolean | null;
+  plan_execution_text?: string | null;
+  plan_execution_json?: unknown;
+  stats?: string | null;
+  recommendations?: string | null;
+  error?: string | null;
 }
 
 export interface ProjectListItem {
-  project_id: number;
+  project_id: number | string;
   alias: string | null;
   name: string | null;
-  label: string | null;
-  /** Whether the project's single Joe instance is `joe_api_v2_enabled` + conformant. */
+  /** Whether the project's single Joe instance is ready for Joe API v2. */
   joe_ready: boolean;
   /** Whether the project's DBLab tunnel is connected. */
   tunnel: boolean;
-  /** The project's active JOE instance id (the M1a submit/status/result target). */
-  instance_id: number | null;
-  /** The project's active DBLAB instance id — the SPEC §8 DBLab-companion resolver
-   * passes this to `v1.dblab_api_call` (distinct from the Joe `instance_id`). */
-  dblab_instance_id: number | null;
+  /** The project's active JOE instance id — the `joe_command_run` target. */
+  instance_id: number | string | null;
+  /** The project's active DBLAB instance id (not used by the Joe verbs). */
+  dblab_instance_id: number | string | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -137,6 +97,7 @@ interface RpcCallParams {
   body: Record<string, unknown>;
   operation: string;
   debug?: boolean;
+  timeoutMs?: number;
 }
 
 async function callRpc<T>(params: RpcCallParams): Promise<T> {
@@ -159,19 +120,24 @@ async function callRpc<T>(params: RpcCallParams): Promise<T> {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
     console.error(`Debug: POST URL: ${url.toString()}`);
     console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-    // Redact credential-shaped fields before logging — the MCP caller controls
-    // the debug flag (mirrors the access-token header masking above).
+    // Redact credential-shaped fields before logging (mirrors the access-token
+    // header masking above).
     console.error(`Debug: Request body: ${redactSecretsForLog(payload)}`);
   }
 
   let response: Response;
+  const requestTimeout = requestTimeoutSignal(params.timeoutMs);
   try {
     response = await fetch(url.toString(), {
       method: "POST",
       headers,
       body: payload,
+      signal: requestTimeout.signal,
     });
   } catch (err) {
+    if (isFetchTimeout(err)) {
+      throw new HttpRequestTimeoutError(operation, requestTimeout.timeoutMs);
+    }
     // A transport failure (connection refused, DNS, TLS, bad host/port) never
     // reaches `response.ok`; undici throws with the real reason in `err.cause`.
     // Surface it — a bare "fetch failed" hides which URL/why. See util.describeFetchError.
@@ -187,16 +153,21 @@ 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. 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));
+    // HTTP 403, PT404 → 404, etc. The RPC's user-facing message may ride in the
+    // HTTP reason phrase (statusText) or the JSON body — pass both through.
+    // The status rides on the Error so the poll loop can classify retryability.
+    throw new HttpStatusError(
+      formatHttpError(operation, response.status, text, response.statusText),
+      response.status
+    );
   }
 
   try {
     return JSON.parse(text) as T;
   } catch {
-    throw new Error(`${operation}: failed to parse response: ${text}`);
+    // Non-JSON body — redact before embedding: this Error reaches CLI stderr
+    // and must not bypass the debug-log redaction.
+    throw new Error(`${operation}: failed to parse response: ${redactSecretsForLog(text)}`);
   }
 }
 
@@ -204,83 +175,69 @@ async function callRpc<T>(params: RpcCallParams): Promise<T> {
 // Individual rpc client functions
 // ---------------------------------------------------------------------------
 
-export interface SubmitCommandParams {
+export interface StartCommandParams {
   apiKey: string;
   apiBaseUrl: string;
-  command: JoeCommand;
-  projectId: number;
-  sql?: string | null;
-  args?: Record<string, unknown> | null;
-  /** 64-bit session id, carried verbatim as a string to avoid precision loss. */
-  sessionId?: string | null;
-  idempotencyKey?: string | null;
+  /** The project's Joe instance id (resolve via {@link resolveJoeInstanceId}). */
+  instanceId: number | string;
+  /** The RAW command text Joe dispatches (e.g. `plan select 1`, `\d users`). */
+  command: string;
   debug?: boolean;
+  timeoutMs?: number;
 }
 
-/** Submit a Joe command (`v1.joe_command_submit`); returns the queued handle. */
-export async function submitCommand(params: SubmitCommandParams): Promise<JoeSubmitResponse> {
-  const { apiKey, apiBaseUrl, command, projectId, sql, args, sessionId, idempotencyKey, debug } = params;
-  if (!JOE_COMMANDS.includes(command)) {
-    throw new Error(`Unknown Joe command: ${command}`);
-  }
-  const body: Record<string, unknown> = {
-    project_id: projectId,
-    command,
-    sql: sql ?? null,
-    args: args ?? null,
-    // session_id is a bigint server-side; sent as a numeric string when known so a
-    // 64-bit id survives JS number precision, null to start a fresh session/clone.
-    session_id: sessionId ?? null,
-  };
-  if (idempotencyKey) {
-    body.idempotency_key = idempotencyKey;
+/**
+ * Start a Joe command (`v1.joe_command_run`); returns the command id.
+ * The rpc returns the id as a JSON string and it stays a string end-to-end —
+ * a bigint id would lose precision beyond 2^53 as a JS number.
+ */
+export async function startCommand(params: StartCommandParams): Promise<string> {
+  const { apiKey, apiBaseUrl, instanceId, command, debug, timeoutMs } = params;
+  if (!String(command ?? "").trim()) {
+    throw new Error("command text is required");
   }
-  return callRpc<JoeSubmitResponse>({
+  const commandId = await callRpc<unknown>({
     apiKey,
     apiBaseUrl,
-    fn: "joe_command_submit",
-    body,
-    operation: `Failed to submit ${command} command`,
+    fn: "joe_command_run",
+    body: { instance_id: instanceId, command },
+    operation: "Failed to run Joe command",
     debug,
+    timeoutMs,
   });
+  if (typeof commandId !== "string" || !/^[0-9]+$/.test(commandId)) {
+    throw new Error(
+      `Failed to run Joe command: expected a command id string, got: ${redactSecretsForLog(JSON.stringify(commandId))}`
+    );
+  }
+  return commandId;
 }
 
-export interface CommandIdParams {
+export interface CommandOutputParams {
   apiKey: string;
   apiBaseUrl: string;
   commandId: string;
   debug?: boolean;
+  timeoutMs?: number;
 }
 
-/** Poll a command's status metadata (`v1.joe_command_status`). */
-export async function getCommandStatus(params: CommandIdParams): Promise<JoeStatusResponse> {
-  const { apiKey, apiBaseUrl, commandId, debug } = params;
-  if (!commandId) {
-    throw new Error("commandId is required");
-  }
-  return callRpc<JoeStatusResponse>({
-    apiKey,
-    apiBaseUrl,
-    fn: "joe_command_status",
-    body: { command_id: commandId },
-    operation: "Failed to fetch command status",
-    debug,
-  });
-}
-
-/** Fetch a command's result body (`v1.joe_command_result`). */
-export async function getCommandResult(params: CommandIdParams): Promise<JoeCommandResult> {
-  const { apiKey, apiBaseUrl, commandId, debug } = params;
+/**
+ * Poll a command's output (`v1.joe_command_output`) — returns the status AND
+ * the full result body in one call (`pending` until Joe posts the result).
+ */
+export async function getCommandOutput(params: CommandOutputParams): Promise<JoeCommandOutput> {
+  const { apiKey, apiBaseUrl, commandId, debug, timeoutMs } = params;
   if (!commandId) {
     throw new Error("commandId is required");
   }
-  return callRpc<JoeCommandResult>({
+  return callRpc<JoeCommandOutput>({
     apiKey,
     apiBaseUrl,
-    fn: "joe_command_result",
+    fn: "joe_command_output",
     body: { command_id: commandId },
-    operation: "Failed to fetch command result",
+    operation: "Failed to fetch command output",
     debug,
+    timeoutMs,
   });
 }
 
@@ -292,37 +249,37 @@ export interface ListProjectsParams {
 }
 
 interface RawProjectRow {
-  id?: number;
-  project_id?: number;
+  project_id?: number | string;
   alias?: string | null;
   name?: string | null;
-  label?: string | null;
   joe_ready?: boolean;
-  joe_api_v2_enabled?: boolean;
   tunnel?: boolean;
-  tunnel_ready?: boolean;
-  instance_id?: number | null;
-  dblab_instance_id?: number | null;
+  instance_id?: number | string | null;
+  dblab_instance_id?: number | string | null;
+}
+
+function preserveIntegerId(value: number | string): number | string {
+  if (typeof value === "number") return value;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : value;
 }
 
 function normalizeProjectRow(row: RawProjectRow): ProjectListItem {
-  const projectId = row.project_id ?? row.id ?? 0;
   return {
-    project_id: Number(projectId),
+    project_id: preserveIntegerId(row.project_id ?? 0),
     alias: row.alias ?? null,
     name: row.name ?? null,
-    label: row.label ?? null,
-    joe_ready: Boolean(row.joe_ready ?? row.joe_api_v2_enabled ?? false),
-    tunnel: Boolean(row.tunnel ?? row.tunnel_ready ?? false),
-    instance_id: row.instance_id == null ? null : Number(row.instance_id),
-    dblab_instance_id: row.dblab_instance_id == null ? null : Number(row.dblab_instance_id),
+    joe_ready: Boolean(row.joe_ready ?? false),
+    tunnel: Boolean(row.tunnel ?? false),
+    instance_id: row.instance_id == null ? null : preserveIntegerId(row.instance_id),
+    dblab_instance_id: row.dblab_instance_id == null ? null : preserveIntegerId(row.dblab_instance_id),
   };
 }
 
 /**
- * List the org's projects (org-level discovery — NOT a Joe endpoint; SPEC §6).
- * Backed by the general platform projects rpc, extended by item S.1 to surface the
- * per-project `joe_ready` + `tunnel` state so an agent knows which it may address.
+ * List the org's projects (org-level discovery — NOT a Joe endpoint).
+ * Surfaces the per-project `joe_ready` + `tunnel` state and the Joe
+ * `instance_id` the run rpc keys on.
  */
 export async function listProjects(params: ListProjectsParams): Promise<ProjectListItem[]> {
   const { apiKey, apiBaseUrl, orgId, debug } = params;
@@ -345,7 +302,7 @@ export async function listProjects(params: ListProjectsParams): Promise<ProjectL
 }
 
 // ---------------------------------------------------------------------------
-// Project id-or-alias resolution (S.0)
+// Project id-or-alias → Joe instance resolution
 // ---------------------------------------------------------------------------
 
 /** A bare numeric `--project` value is a project id; anything else is an alias/name. */
@@ -353,7 +310,7 @@ export function isNumericProjectRef(ref: string): boolean {
   return /^[0-9]+$/.test(ref.trim());
 }
 
-export interface ResolveProjectParams {
+export interface ResolveInstanceParams {
   apiKey: string;
   apiBaseUrl: string;
   project: string;
@@ -362,23 +319,16 @@ export interface ResolveProjectParams {
 }
 
 /**
- * Resolve `--project <id|alias>` to a numeric project id. A numeric ref is used
- * directly (no lookup); an alias/name/label is resolved against the projects
- * list, so `--project main-db` ≡ `--project 12` (SPEC §6, finding S.0).
- *
- * NOTE(joe-v2): deliberately kept parallel to dblab.ts `resolveDblabInstanceId`
- * (which additionally needs the project's `dblab_instance_id`); both accept the
- * SAME reference set — id, alias, name, label. Full resolver unification is a
- * deferred refactor.
+ * Resolve `--project <id|alias>` to the project's Joe `instance_id` (what
+ * `joe_command_run` keys on). Unlike a pure project-id resolver, a numeric ref
+ * still needs the projects listing — the instance id lives there. Accepts a
+ * numeric project id, or an alias/name (case-insensitive).
  */
-export async function resolveProjectId(params: ResolveProjectParams): Promise<number> {
+export async function resolveJoeInstanceId(params: ResolveInstanceParams): Promise<number | string> {
   const ref = String(params.project ?? "").trim();
   if (!ref) {
     throw new Error("project is required (--project <id|alias>)");
   }
-  if (isNumericProjectRef(ref)) {
-    return Number(ref);
-  }
   const projects = await listProjects({
     apiKey: params.apiKey,
     apiBaseUrl: params.apiBaseUrl,
@@ -386,108 +336,106 @@ export async function resolveProjectId(params: ResolveProjectParams): Promise<nu
     debug: params.debug,
   });
   const needle = ref.toLowerCase();
-  const match = projects.find(
-    (p) =>
-      (p.alias !== null && p.alias.toLowerCase() === needle) ||
-      (p.name !== null && p.name.toLowerCase() === needle) ||
-      (p.label !== null && p.label.toLowerCase() === needle)
-  );
+  const match = isNumericProjectRef(ref)
+    ? projects.find((p) => String(p.project_id) === String(preserveIntegerId(ref)))
+    : projects.find(
+        (p) =>
+          (p.alias !== null && p.alias.toLowerCase() === needle) ||
+          (p.name !== null && p.name.toLowerCase() === needle)
+      );
   if (!match) {
     throw new Error(
-      `Project not found for alias/name '${ref}'. Run 'pgai projects' to see available projects.`
+      `Project not found for id/alias/name '${ref}'. Run 'pgai projects' to see available projects.`
     );
   }
-  return match.project_id;
+  if (match.instance_id == null) {
+    throw new Error(
+      `Project '${ref}' has no Joe instance. Run 'pgai projects' to see which projects have Joe ready.`
+    );
+  }
+  return match.instance_id;
 }
 
 // ---------------------------------------------------------------------------
-// Per-project session persistence (auto-threaded optimize loop, finding B-1)
+// Raw command text builders (what Joe's /webui/command dispatches)
 // ---------------------------------------------------------------------------
 
-function sessionStorePath(dir?: string): string {
-  return path.join(dir ?? config.getConfigDir(), "joe-sessions.json");
-}
-
-function readSessionStore(dir?: string): Record<string, string> {
-  const file = sessionStorePath(dir);
-  if (!fs.existsSync(file)) {
-    return {};
-  }
-  try {
-    const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as unknown;
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return parsed as Record<string, string>;
-    }
-  } catch {
-    // Corrupt store — treat as empty rather than failing a command.
-  }
-  return {};
-}
-
-export function readStoredSessionId(projectId: number, dir?: string): string | null {
-  const store = readSessionStore(dir);
-  const value = store[String(projectId)];
-  return typeof value === "string" && value.length > 0 ? value : null;
-}
-
-export function writeStoredSessionId(projectId: number, sessionId: string, dir?: string): void {
-  const baseDir = dir ?? config.getConfigDir();
-  if (!fs.existsSync(baseDir)) {
-    fs.mkdirSync(baseDir, { recursive: true, mode: 0o700 });
-  }
-  const store = readSessionStore(dir);
-  store[String(projectId)] = sessionId;
-  fs.writeFileSync(sessionStorePath(dir), JSON.stringify(store, null, 2) + "\n", { mode: 0o600 });
-}
+/** The \d-family variants Joe's psql allowlist accepts (`describe --variant`). */
+export const DESCRIBE_VARIANTS = [
+  "\\d",
+  "\\d+",
+  "\\dt",
+  "\\dt+",
+  "\\di",
+  "\\di+",
+  "\\l",
+  "\\l+",
+  "\\dv",
+  "\\dv+",
+  "\\dm",
+  "\\dm+",
+] as const;
 
-export function clearStoredSessionId(projectId: number, dir?: string): void {
-  const file = sessionStorePath(dir);
-  if (!fs.existsSync(file)) {
-    return;
-  }
-  const store = readSessionStore(dir);
-  if (String(projectId) in store) {
-    delete store[String(projectId)];
-    fs.writeFileSync(file, JSON.stringify(store, null, 2) + "\n", { mode: 0o600 });
-  }
+export interface JoeVerbInput {
+  /** The verb's positional payload: SQL, hypo tail, pid, or object name. */
+  arg?: string | null;
+  /** describe only: the \d-family variant (default `\d`). */
+  variant?: string | null;
 }
 
-// ---------------------------------------------------------------------------
-// Idempotency keys
-// ---------------------------------------------------------------------------
-
 /**
- * Compute the idempotency key for a submit. Executing commands (`exec`/`explain`)
- * mint a STABLE key derived from `(project_id, command, sql, args)` so a
- * timeout-resubmit dedupes back to the original command_id (at-most-once — SPEC M8);
- * non-executing commands generate a fresh per-invocation key.
+ * Build the RAW command text for a verb — exactly what a console user could
+ * type at Joe. The server adds no prefix and does no verb inspection, so this
+ * string is the whole contract (`plan <sql>`, `terminate <pid>`, `\d+ users`).
  */
-export function computeIdempotencyKey(
-  command: JoeCommand,
-  projectId: number,
-  sql: string | null | undefined,
-  args: Record<string, unknown> | null | undefined
-): string {
-  if (EXECUTING_COMMANDS.has(command)) {
-    const canonical = `${projectId}\n${command}\n${sql ?? ""}\n${JSON.stringify(args ?? null)}`;
-    return `joe-${crypto.createHash("sha256").update(canonical).digest("hex")}`;
+export function buildJoeCommandText(command: JoeCommand, input: JoeVerbInput = {}): string {
+  const arg = String(input.arg ?? "").trim();
+  switch (command) {
+    case "plan":
+    case "explain":
+    case "exec":
+    case "hypo": {
+      if (!arg) {
+        throw new Error(`${command} requires an argument`);
+      }
+      return `${command} ${arg}`;
+    }
+    case "activity":
+    case "reset":
+      return command;
+    case "terminate": {
+      // A pid must be a bare positive integer — parseInt() would silently
+      // accept "12x"/"−5"/"1.5" and terminate the WRONG backend.
+      if (!/^[1-9][0-9]*$/.test(arg)) {
+        throw new Error("pid must be a positive integer");
+      }
+      return `terminate ${arg}`;
+    }
+    case "describe": {
+      if (!arg) {
+        throw new Error("describe requires an object name");
+      }
+      const variant = String(input.variant ?? "\\d").trim();
+      if (!(DESCRIBE_VARIANTS as readonly string[]).includes(variant)) {
+        throw new Error(
+          `Unsupported describe variant '${variant}'. Supported: ${DESCRIBE_VARIANTS.join(" ")}`
+        );
+      }
+      return `${variant} ${arg}`;
+    }
   }
-  return `joe-${crypto.randomUUID()}`;
 }
 
 // ---------------------------------------------------------------------------
-// Submit-then-poll one-shot
+// Run-then-poll one-shot
 // ---------------------------------------------------------------------------
 
 export interface RunCommandParams {
   apiKey: string;
   apiBaseUrl: string;
-  command: JoeCommand;
-  projectId: number;
-  sql?: string | null;
-  args?: Record<string, unknown> | null;
-  sessionId?: string | null;
-  idempotencyKey?: string | null;
+  instanceId: number | string;
+  /** The RAW command text (see {@link buildJoeCommandText}). */
+  command: string;
   budgetMs?: number;
   pollIntervalMs?: number;
   debug?: boolean;
@@ -498,11 +446,9 @@ export interface RunCommandParams {
 
 export interface RunCommandOutcome {
   commandId: string;
-  /** The session id returned by submit (thread back / persist for the next command). */
-  sessionId: string | null;
-  status: JoeStatus;
-  /** Populated once the command reaches a terminal state (done/error/timed_out). */
-  result: JoeCommandResult | null;
+  status: JoeOutputStatus;
+  /** Populated once the command reaches a terminal state (ok/error). */
+  output: JoeCommandOutput | null;
   /** True when the ≤ budget one-shot expired before a terminal state — resume by id. */
   budgetExpired: boolean;
 }
@@ -510,132 +456,145 @@ export interface RunCommandOutcome {
 const defaultSleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
 
 /**
- * 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 joe result <command_id>` later.
+ * Run a raw command then poll `joe_command_output` within the one-shot budget.
+ * On a terminal state returns the full output; on budget expiry returns a
+ * resume handle (`budgetExpired: true`) so the caller can
+ * `pgai joe result <command_id>` later.
  */
 export async function runCommand(params: RunCommandParams): Promise<RunCommandOutcome> {
-  const {
-    apiKey,
-    apiBaseUrl,
-    command,
-    projectId,
-    sql,
-    args,
-    sessionId,
-    debug,
-  } = params;
+  const { apiKey, apiBaseUrl, instanceId, command, debug } = params;
   // Defensive: only a finite budget is honored. NaN survives `??` (it is
   // neither null nor undefined) and would make `deadline` NaN — `now() >= NaN`
   // is always false, i.e. an UNBOUNDED poll loop.
   const budgetMs =
-    typeof params.budgetMs === "number" && Number.isFinite(params.budgetMs)
+    typeof params.budgetMs === "number" && Number.isFinite(params.budgetMs) && params.budgetMs >= 0
       ? params.budgetMs
       : DEFAULT_BUDGET_MS;
   const pollIntervalMs = params.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
   const now = params.now ?? Date.now;
   const sleep = params.sleep ?? defaultSleep;
-  const idempotencyKey =
-    params.idempotencyKey ?? computeIdempotencyKey(command, projectId, sql, args);
 
-  const submitted = await submitCommand({
-    apiKey,
-    apiBaseUrl,
-    command,
-    projectId,
-    sql,
-    args,
-    sessionId,
-    idempotencyKey,
-    debug,
-  });
+  const commandId = await startCommand({ apiKey, apiBaseUrl, instanceId, command, debug });
 
-  const commandId = submitted.command_id;
-  const newSessionId = submitted.session_id ?? sessionId ?? null;
   const deadline = now() + budgetMs;
-  let status: JoeStatus = submitted.status;
-
-  // Poll status until terminal or the one-shot budget is exhausted.
-  // eslint-disable-next-line no-constant-condition
-  while (true) {
-    const statusResp = await getCommandStatus({ apiKey, apiBaseUrl, commandId, debug });
-    status = statusResp.status;
-    if (TERMINAL_STATES.has(status)) {
-      break;
+  let status: JoeOutputStatus = "pending";
+  const remainingRequestMs = (): number =>
+    Math.max(1, Math.min(DEFAULT_HTTP_REQUEST_TIMEOUT_MS, deadline - now()));
+
+  // A zero/tiny budget may already be exhausted by the run round-trip. Do not
+  // start an output request with a nominal 1ms timeout; return the valid
+  // command handle immediately so the caller can resume deterministically.
+  if (now() >= deadline) {
+    return { commandId, status, output: null, budgetExpired: true };
+  }
+
+  // Poll the output until terminal or the one-shot budget is exhausted.
+  for (;;) {
+    let output: JoeCommandOutput;
+    try {
+      output = await getCommandOutput({
+        apiKey,
+        apiBaseUrl,
+        commandId,
+        debug,
+        timeoutMs: remainingRequestMs(),
+      });
+    } catch (err) {
+      if (err instanceof HttpRequestTimeoutError) {
+        return { commandId, status, output: null, budgetExpired: true };
+      }
+      if (err instanceof HttpStatusError && isRetryableHttpStatus(err.status)) {
+        // Transient output failure (5xx proxy hiccup / Joe pod restart, or a
+        // 429 rate limit) — the run rpc already returned a VALID command id,
+        // so never throw it away: keep polling within the budget, then hand
+        // back the resume handle (`pgai joe result <id>`) instead of failing.
+        if (now() >= deadline) {
+          return { commandId, status, output: null, budgetExpired: true };
+        }
+        await sleep(pollIntervalMs);
+        continue;
+      }
+      // Terminal (PT400/PT401/PT403/PT404 and other non-retryable errors):
+      // abort loudly — polling on cannot succeed.
+      throw err;
+    }
+    status = output.status;
+    if (status === "ok" || status === "error") {
+      return { commandId, status, output, budgetExpired: false };
     }
     if (now() >= deadline) {
-      return { commandId, sessionId: newSessionId, status, result: null, budgetExpired: true };
+      return { commandId, status, output: null, budgetExpired: true };
     }
     await sleep(pollIntervalMs);
   }
-
-  const result = await getCommandResult({ apiKey, apiBaseUrl, commandId, debug });
-  return { commandId, sessionId: newSessionId, status, result, budgetExpired: false };
 }
 
 // ---------------------------------------------------------------------------
-// High-level orchestrator shared by the CLI and MCP surfaces
+// High-level orchestrator (the CLI verb surface)
 // ---------------------------------------------------------------------------
 
 export interface ExecuteJoeParams {
   apiKey: string;
   apiBaseUrl: string;
   command: JoeCommand;
-  /** Raw `--project <id|alias>` value. */
-  project: string;
-  sql?: string | null;
-  args?: Record<string, unknown> | null;
-  /** Explicit `--session <id>` (overrides the stored/auto session). */
-  session?: string | null;
-  /** `--new-session` — force a fresh clone (null session). */
-  newSession?: boolean;
+  /** Raw `--project <id|alias>` value (resolved via `projects_list`). */
+  project?: string;
+  /**
+   * Direct `--instance-id` value — skips project resolution entirely (the v1
+   * path while `projects_list` is not deployed). Kept a string end-to-end so
+   * a 64-bit id never rounds through a JS number; PostgREST casts it to the
+   * rpc's bigint param. Wins over `project` when both are given.
+   */
+  instanceId?: number | string;
+  input?: JoeVerbInput;
   orgId?: number;
   budgetMs?: number;
   pollIntervalMs?: number;
   debug?: boolean;
-  /** Session-store directory (defaults to the user config dir). */
-  sessionDir?: string;
   now?: () => number;
   sleep?: (ms: number) => Promise<void>;
 }
 
 export interface ExecuteJoeOutcome extends RunCommandOutcome {
   command: JoeCommand;
-  projectId: number;
+  instanceId: number | string;
+  /** The raw text that went on the wire (debugging/tests). */
+  commandText: string;
 }
 
 /**
- * Resolve the project (id-or-alias), pick the session (explicit / stored / new),
- * run the submit-then-poll one-shot, and persist the returned session for the next
- * command on the same project — the auto-threaded optimize loop.
+ * Build the raw command text from the verb, target the Joe instance (directly
+ * via `instanceId`, or by resolving the project id-or-alias), and run the
+ * one-shot. The text is built FIRST so a bad verb argument (e.g. a garbage
+ * pid) fails before any network call.
  */
 export async function executeJoeCommand(params: ExecuteJoeParams): Promise<ExecuteJoeOutcome> {
-  const projectId = await resolveProjectId({
-    apiKey: params.apiKey,
-    apiBaseUrl: params.apiBaseUrl,
-    project: params.project,
-    orgId: params.orgId,
-    debug: params.debug,
-  });
+  const commandText = buildJoeCommandText(params.command, params.input);
 
-  let sessionId: string | null;
-  if (params.newSession) {
-    clearStoredSessionId(projectId, params.sessionDir);
-    sessionId = null;
-  } else if (params.session) {
-    sessionId = String(params.session);
+  let instanceId: number | string;
+  const directRef = String(params.instanceId ?? "").trim();
+  if (directRef) {
+    if (!/^[0-9]+$/.test(directRef)) {
+      throw new Error("instanceId must be a numeric Joe instance id");
+    }
+    instanceId = directRef;
+  } else if (String(params.project ?? "").trim()) {
+    instanceId = await resolveJoeInstanceId({
+      apiKey: params.apiKey,
+      apiBaseUrl: params.apiBaseUrl,
+      project: String(params.project),
+      orgId: params.orgId,
+      debug: params.debug,
+    });
   } else {
-    sessionId = readStoredSessionId(projectId, params.sessionDir);
+    throw new Error("either instanceId or project is required");
   }
 
   const outcome = await runCommand({
     apiKey: params.apiKey,
     apiBaseUrl: params.apiBaseUrl,
-    command: params.command,
-    projectId,
-    sql: params.sql,
-    args: params.args,
-    sessionId,
+    instanceId,
+    command: commandText,
     budgetMs: params.budgetMs,
     pollIntervalMs: params.pollIntervalMs,
     debug: params.debug,
@@ -643,11 +602,7 @@ export async function executeJoeCommand(params: ExecuteJoeParams): Promise<Execu
     sleep: params.sleep,
   });
 
-  if (outcome.sessionId) {
-    writeStoredSessionId(projectId, outcome.sessionId, params.sessionDir);
-  }
-
-  return { ...outcome, command: params.command, projectId };
+  return { ...outcome, command: params.command, instanceId, commandText };
 }
 
 // ---------------------------------------------------------------------------
@@ -662,9 +617,8 @@ interface PlanNode {
 }
 
 /**
- * Lightweight CLIENT-SIDE plan flagging (SPEC §6). The API returns no
- * server-authored recommendations (dropped as an injection vector), so the CLI
- * flags obvious issues (e.g. a Seq Scan) from the returned plan_json itself.
+ * Lightweight CLIENT-SIDE plan flagging: flag obvious issues (e.g. a Seq Scan)
+ * from the returned structured plan_json itself.
  */
 export function clientSidePlanFlags(planJson: unknown): string[] {
   const flags: string[] = [];
@@ -685,6 +639,15 @@ export function clientSidePlanFlags(planJson: unknown): string[] {
       }
     }
   };
+  if (Array.isArray(planJson)) {
+    // EXPLAIN (format json) returns an array: [{ "Plan": { … } }].
+    for (const entry of planJson) {
+      if (entry && typeof entry === "object") {
+        walk((entry as { Plan?: PlanNode }).Plan ?? (entry as PlanNode));
+      }
+    }
+    return flags;
+  }
   if (planJson && typeof planJson === "object") {
     const root = planJson as { Plan?: PlanNode };
     walk(root.Plan ?? (planJson as PlanNode));
@@ -692,57 +655,36 @@ export function clientSidePlanFlags(planJson: unknown): string[] {
   return flags;
 }
 
-/** Format a terminal command result as human-readable text (non-JSON mode). */
-export function formatJoeResult(command: JoeCommand, result: JoeCommandResult): string {
+/**
+ * Format a terminal command output as human-readable text (non-JSON mode).
+ * The sync contract returns one uniform row for every verb, so this prints
+ * whichever sections are present rather than switching per command.
+ */
+export function formatJoeOutput(output: JoeCommandOutput): string {
   const lines: string[] = [];
-  switch (command) {
-    case "plan":
-    case "explain": {
-      if (result.plan_text) {
-        lines.push(result.plan_text);
-      }
-      for (const flag of clientSidePlanFlags(result.plan_json)) {
-        lines.push(`⚑ ${flag}`);
-      }
-      if (result.queryid || result.plan_fingerprint) {
-        lines.push(`(queryid ${result.queryid ?? "?"} · plan_fp ${result.plan_fingerprint ?? "?"})`);
-      }
-      break;
-    }
-    case "exec": {
-      const notices = result.notices ?? [];
-      const rowCount = result.row_count ?? 0;
-      lines.push(`${notices.join(" ") || "OK"} · ${rowCount} row${rowCount === 1 ? "" : "s"}`);
-      if (result.result_rows && result.result_rows.length > 0) {
-        lines.push(JSON.stringify(result.result_rows, null, 2));
-      }
-      break;
-    }
-    case "hypo": {
-      lines.push(result.hypo_used ? "hypothetical index would be used" : "hypothetical index would NOT be used");
-      if (result.hypo_plan !== undefined) {
-        lines.push(JSON.stringify(result.hypo_plan, null, 2));
-      }
-      break;
-    }
-    case "activity":
-    case "describe": {
-      lines.push(JSON.stringify(result.snapshot ?? null, null, 2));
-      break;
-    }
-    case "terminate": {
-      lines.push(`terminated ${result.terminated ? "yes" : "no"} · pid ${result.pid ?? "?"}`);
-      break;
-    }
-    case "reset": {
-      lines.push(`reset ${result.reset ? "ok" : "no"}`);
-      break;
-    }
+  const section = (value: string | null | undefined, label?: string): void => {
+    if (value == null || value.trim() === "") return;
+    if (lines.length > 0) lines.push("");
+    if (label) lines.push(`${label}:`);
+    lines.push(value);
+  };
+  section(output.response);
+  section(output.plan_text, "plan");
+  const flags = clientSidePlanFlags(output.plan_json).map((flag) => `⚑ ${flag}`);
+  if (flags.length > 0) {
+    lines.push(...flags);
+  }
+  section(output.plan_execution_text, "execution plan (EXPLAIN ANALYZE)");
+  section(output.stats, "stats");
+  section(output.recommendations, "recommendations");
+  if (output.queryid) {
+    if (lines.length > 0) lines.push("");
+    lines.push(`(queryid ${output.queryid})`);
   }
   return lines.join("\n");
 }
 
-/** Render `pgai projects` as the brief's fixed-width table. */
+/** Render `pgai projects` as a fixed-width table. */
 export function formatProjectsTable(projects: ProjectListItem[]): string {
   const header = ["PROJECT_ID", "ALIAS", "PROJECT", "JOE", "TUNNEL"];
   const rows = projects.map((p) => [