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

package/test/joe.test.ts

@@ -1,28 +1,21 @@
 import { describe, test, expect, mock, afterEach, spyOn } from "bun:test";
-import { mkdtempSync, existsSync, readFileSync } from "fs";
-import { tmpdir } from "os";
-import { resolve } from "path";
 import {
-  submitCommand,
-  getCommandStatus,
-  getCommandResult,
+  startCommand,
+  getCommandOutput,
   listProjects,
-  resolveProjectId,
+  resolveJoeInstanceId,
   isNumericProjectRef,
-  computeIdempotencyKey,
+  buildJoeCommandText,
   runCommand,
   executeJoeCommand,
-  readStoredSessionId,
-  writeStoredSessionId,
-  clearStoredSessionId,
   clientSidePlanFlags,
   formatProjectsTable,
-  formatJoeResult,
+  formatJoeOutput,
   JOE_COMMANDS,
+  DESCRIBE_VARIANTS,
   type JoeCommand,
-  type JoeStatus,
+  type JoeCommandOutput,
 } from "../lib/joe";
-import { handleToolCall, joeToolDefinitions, sanitizeBudgetMs, JOE_TOOL_TO_COMMAND, type McpToolRequest } from "../lib/mcp-server";
 
 const BASE = "https://api.example.com";
 const originalFetch = globalThis.fetch;
@@ -54,136 +47,203 @@ function json(obj: unknown, status = 200): Response {
   return new Response(JSON.stringify(obj), { status, headers: { "Content-Type": "application/json" } });
 }
 
-function tempDir(): string {
-  return mkdtempSync(resolve(tmpdir(), "joe-test-"));
-}
-
 afterEach(() => {
   globalThis.fetch = originalFetch;
 });
 
-describe("submitCommand", () => {
+describe("startCommand (joe_command_run)", () => {
   test("throws when apiKey missing", async () => {
     await expect(
-      submitCommand({ apiKey: "", apiBaseUrl: BASE, command: "plan", projectId: 12 })
+      startCommand({ apiKey: "", apiBaseUrl: BASE, instanceId: 3, command: "plan select 1" })
     ).rejects.toThrow("API key is required");
   });
 
-  test("maps to /rpc/joe_command_submit with the correct payload", async () => {
-    const captured = installFetch({
-      joe_command_submit: () => json({ command_id: "4711", session_id: "88", status: "queued" }),
-    });
-    const res = await submitCommand({
+  test("throws on empty command text before any network call", async () => {
+    const captured = installFetch({ joe_command_run: () => json("1") });
+    await expect(
+      startCommand({ apiKey: "k", apiBaseUrl: BASE, instanceId: 3, command: "   " })
+    ).rejects.toThrow("command text is required");
+    expect(captured.length).toBe(0);
+  });
+
+  test("maps to /rpc/joe_command_run with {instance_id, command} and the access-token header", async () => {
+    const captured = installFetch({ joe_command_run: () => json("4711") });
+    const id = await startCommand({
       apiKey: "k",
       apiBaseUrl: BASE,
-      command: "plan",
-      projectId: 12,
-      sql: "select 1",
-      sessionId: "88",
-      idempotencyKey: "idem-1",
+      instanceId: 3,
+      command: "plan select 1",
     });
-    expect(captured[0].url).toBe(`${BASE}/rpc/joe_command_submit`);
+    expect(captured[0].url).toBe(`${BASE}/rpc/joe_command_run`);
     expect(captured[0].headers["access-token"]).toBe("k");
-    expect(captured[0].body).toEqual({
-      project_id: 12,
-      command: "plan",
-      sql: "select 1",
-      args: null,
-      session_id: "88",
-      idempotency_key: "idem-1",
-    });
-    expect(res).toEqual({ command_id: "4711", session_id: "88", status: "queued" });
+    // The RAW command text goes on the wire — no structured body, no prefixing.
+    expect(captured[0].body).toEqual({ instance_id: 3, command: "plan select 1" });
+    expect(id).toBe("4711");
   });
 
-  test("sends null sql/session_id and args for structured commands", async () => {
-    const captured = installFetch({
-      joe_command_submit: () => json({ command_id: "1", session_id: null, status: "queued" }),
-    });
-    await submitCommand({
-      apiKey: "k",
-      apiBaseUrl: BASE,
-      command: "terminate",
-      projectId: 5,
-      args: { pid: 4711 },
-      idempotencyKey: "x",
-    });
-    expect(captured[0].body.sql).toBeNull();
-    expect(captured[0].body.session_id).toBeNull();
-    expect(captured[0].body.args).toEqual({ pid: 4711 });
+  test("the command id STAYS a string — a >2^53 id survives verbatim", async () => {
+    // joe_command_run returns to_json(id::text). Any parseInt/Number round-trip
+    // would corrupt 9007199254740993 to 9007199254740992.
+    installFetch({ joe_command_run: () => json("9007199254740993") });
+    const id = await startCommand({ apiKey: "k", apiBaseUrl: BASE, instanceId: 3, command: "reset" });
+    expect(id).toBe("9007199254740993");
+    expect(typeof id).toBe("string");
   });
 
-  test("surfaces the ai_enabled=false PT403 disabled-AI message", async () => {
+  test("a non-string rpc reply is rejected (contract violation)", async () => {
+    installFetch({ joe_command_run: () => json({ command_id: "1" }) });
+    await expect(
+      startCommand({ apiKey: "k", apiBaseUrl: BASE, instanceId: 3, command: "reset" })
+    ).rejects.toThrow(/expected a command id string/);
+  });
+
+  test("a bare-number id is rejected — the whole point of the precision guard", async () => {
+    // If the backend ever returned to_json(id) instead of to_json(id::text),
+    // JSON.parse would have ALREADY rounded 9007199254740993 → ...992; a
+    // number must never be silently String()ed back.
+    installFetch({ joe_command_run: () => json(9007199254740993) });
+    await expect(
+      startCommand({ apiKey: "k", apiBaseUrl: BASE, instanceId: 3, command: "reset" })
+    ).rejects.toThrow(/expected a command id string/);
+  });
+
+  test("a 401 rejects with the auth remediation hint", async () => {
+    installFetch({ joe_command_run: () => json({ message: "JWT expired" }, 401) });
+    let thrown: Error | null = null;
+    try {
+      await startCommand({ apiKey: "k", apiBaseUrl: BASE, instanceId: 3, command: "plan select 1" });
+    } catch (err) {
+      thrown = err as Error;
+    }
+    expect(thrown?.message).toContain("HTTP 401");
+    expect(thrown?.message).toContain("JWT expired");
+    expect(thrown?.message).toContain("postgresai auth");
+  });
+
+  test("a 502 on run rejects legibly (no id exists yet — nothing to resume)", async () => {
+    installFetch({ joe_command_run: () => new Response("Bad Gateway", { status: 502 }) });
+    await expect(
+      startCommand({ apiKey: "k", apiBaseUrl: BASE, instanceId: 3, command: "plan select 1" })
+    ).rejects.toThrow(/Failed to run Joe command: HTTP 502/);
+  });
+
+  test("surfaces the missing-role PT403 detail from the JSON body", async () => {
     installFetch({
-      joe_command_submit: () =>
-        json({ message: "AI features disabled for this org — enable in AI Assistant Settings" }, 403),
+      joe_command_run: () =>
+        json({ code: "PT403", message: "Forbidden", details: "Joe API v2 requires the All Features role." }, 403),
     });
     await expect(
-      submitCommand({ apiKey: "k", apiBaseUrl: BASE, command: "plan", projectId: 12, sql: "select 1" })
-    ).rejects.toThrow(/AI features disabled for this org/);
+      startCommand({ apiKey: "k", apiBaseUrl: BASE, instanceId: 3, command: "plan select 1" })
+    ).rejects.toThrow(/Joe API v2 requires the All Features role/);
   });
 
-  test("surfaces a scope refusal (PT403)", async () => {
+  test("surfaces a PT403 reason phrase when PostgREST returns no JSON body", async () => {
     installFetch({
-      joe_command_submit: () => json({ message: "missing scope joe:exec" }, 403),
+      joe_command_run: () => new Response(null, {
+        status: 403,
+        statusText: "Joe API v2 requires the All Features role.",
+      }),
     });
     await expect(
-      submitCommand({ apiKey: "k", apiBaseUrl: BASE, command: "exec", projectId: 12, sql: "create index" })
-    ).rejects.toThrow(/missing scope joe:exec/);
+      startCommand({ apiKey: "k", apiBaseUrl: BASE, instanceId: 3, command: "plan select 1" })
+    ).rejects.toThrow("Joe API v2 requires the All Features role.");
   });
-});
 
-describe("getCommandStatus / getCommandResult", () => {
-  test("status maps to /rpc/joe_command_status with command_id", async () => {
-    const captured = installFetch({
-      joe_command_status: () => json({ command_id: "4711", status: "running", error: null }),
+  test("a non-JSON body embedded in the parse-failure error is redacted", async () => {
+    // The thrown Error flows into CLI stderr — a body echoing credentials must
+    // not bypass redaction on this path.
+    installFetch({
+      joe_command_run: () => new Response("oops password=hunter2 dsn=postgresql://joe:pw-abc@h/db", { status: 200 }),
     });
-    const res = await getCommandStatus({ apiKey: "k", apiBaseUrl: BASE, commandId: "4711" });
-    expect(captured[0].url).toBe(`${BASE}/rpc/joe_command_status`);
-    expect(captured[0].body).toEqual({ command_id: "4711" });
-    expect(res.status).toBe("running");
+    let thrown: Error | null = null;
+    try {
+      await startCommand({ apiKey: "k", apiBaseUrl: BASE, instanceId: 3, command: "plan select 1" });
+    } catch (err) {
+      thrown = err as Error;
+    }
+    expect(thrown?.message).toContain("failed to parse response");
+    expect(thrown?.message).not.toContain("hunter2");
+    expect(thrown?.message).not.toContain("pw-abc");
   });
+});
 
-  test("result maps to /rpc/joe_command_result and returns the plan body", async () => {
+describe("getCommandOutput (joe_command_output)", () => {
+  test("maps to /rpc/joe_command_output with {command_id} and returns the FULL body", async () => {
     const captured = installFetch({
-      joe_command_result: () =>
+      joe_command_output: () =>
         json({
           command_id: "4711",
-          status: "done",
-          queryid: "77",
-          plan_fingerprint: "a1b2",
+          status: "ok",
+          created_at: "2026-07-22T10:00:00",
+          command: "explain",
+          query: "select * from users",
+          queryid: "7712349901234567890",
+          response: null,
           plan_text: "Seq Scan on users",
-          plan_json: { Plan: { "Node Type": "Seq Scan", "Relation Name": "users" } },
+          plan_json: [{ Plan: { "Node Type": "Seq Scan", "Relation Name": "users" } }],
+          plan_execution_text: "Seq Scan on users (actual time=0.1..12.3)",
+          plan_execution_json: [{ Plan: {} }],
+          stats: "Time: 12.4 ms",
+          recommendations: ":warning: Seq Scan",
           error: null,
         }),
     });
-    const res = await getCommandResult({ apiKey: "k", apiBaseUrl: BASE, commandId: "4711" });
-    expect(captured[0].url).toBe(`${BASE}/rpc/joe_command_result`);
-    expect(res.plan_text).toBe("Seq Scan on users");
+    const output = await getCommandOutput({ apiKey: "k", apiBaseUrl: BASE, commandId: "4711" });
+    expect(captured[0].url).toBe(`${BASE}/rpc/joe_command_output`);
+    expect(captured[0].body).toEqual({ command_id: "4711" });
+    expect(output.status).toBe("ok");
+    expect(output.plan_text).toBe("Seq Scan on users");
+    expect(output.plan_execution_text).toContain("actual time");
+    expect(output.stats).toBe("Time: 12.4 ms");
+    // plan_json arrives structured (the rpc unwraps the stored jsonb string).
+    expect(Array.isArray(output.plan_json)).toBe(true);
+  });
+
+  test("a 'pending' body (no result columns yet) passes through", async () => {
+    installFetch({
+      joe_command_output: () => json({ command_id: "4711", status: "pending", created_at: "2026-07-22T10:00:00" }),
+    });
+    const output = await getCommandOutput({ apiKey: "k", apiBaseUrl: BASE, commandId: "4711" });
+    expect(output.status).toBe("pending");
+    expect(output.plan_text).toBeUndefined();
   });
 
-  test("PT404 (not found / out-of-allowlist) surfaces as an error", async () => {
+  test("PT404 (not found / other org) surfaces as an error", async () => {
     installFetch({
-      joe_command_status: () => json({ message: "command not found" }, 404),
+      joe_command_output: () => json({ code: "PT404", message: "Not found", details: "Specified command not found." }, 404),
     });
     await expect(
-      getCommandStatus({ apiKey: "k", apiBaseUrl: BASE, commandId: "9999" })
-    ).rejects.toThrow(/Failed to fetch command status/);
+      getCommandOutput({ apiKey: "k", apiBaseUrl: BASE, commandId: "9999" })
+    ).rejects.toThrow(/Failed to fetch command output/);
+  });
+
+  test("requires a commandId", async () => {
+    await expect(
+      getCommandOutput({ apiKey: "k", apiBaseUrl: BASE, commandId: "" })
+    ).rejects.toThrow("commandId is required");
+  });
+
+  test("a 502 rejects legibly (never mistaken for success)", async () => {
+    installFetch({ joe_command_output: () => new Response("<html>Bad Gateway</html>", { status: 502 }) });
+    await expect(
+      getCommandOutput({ apiKey: "k", apiBaseUrl: BASE, commandId: "1" })
+    ).rejects.toThrow(/Failed to fetch command output: HTTP 502/);
   });
 });
 
 describe("listProjects", () => {
-  test("normalizes id/joe_api_v2_enabled/tunnel variants", async () => {
+  test("normalizes rows and defaults missing optional fields", async () => {
     installFetch({
       projects_list: () =>
         json([
-          { id: 12, alias: "main-db", name: "Main DB", label: "Main DB", joe_api_v2_enabled: true, tunnel_ready: true, instance_id: 3, dblab_instance_id: 7 },
+          { project_id: 12, alias: "main-db", name: "Main DB", joe_ready: true, tunnel: true, instance_id: 3, dblab_instance_id: 7 },
           { project_id: 13, alias: "dw", name: "Warehouse", joe_ready: false, tunnel: false },
         ]),
     });
     const projects = await listProjects({ apiKey: "k", apiBaseUrl: BASE });
     expect(projects).toEqual([
-      { project_id: 12, alias: "main-db", name: "Main DB", label: "Main DB", joe_ready: true, tunnel: true, instance_id: 3, dblab_instance_id: 7 },
-      { project_id: 13, alias: "dw", name: "Warehouse", label: null, joe_ready: false, tunnel: false, instance_id: null, dblab_instance_id: null },
+      { project_id: 12, alias: "main-db", name: "Main DB", joe_ready: true, tunnel: true, instance_id: 3, dblab_instance_id: 7 },
+      { project_id: 13, alias: "dw", name: "Warehouse", joe_ready: false, tunnel: false, instance_id: null, dblab_instance_id: null },
     ]);
   });
 
@@ -192,9 +252,29 @@ describe("listProjects", () => {
     await listProjects({ apiKey: "k", apiBaseUrl: BASE, orgId: 7 });
     expect(captured[0].body).toEqual({ org_id: 7 });
   });
+
+  test("preserves 64-bit project and instance ids without Number precision loss", async () => {
+    installFetch({
+      projects_list: () => json([{
+        project_id: "9007199254740993",
+        alias: "huge",
+        instance_id: "9007199254740994",
+        dblab_instance_id: "9007199254740995",
+      }]),
+    });
+    const [project] = await listProjects({ apiKey: "k", apiBaseUrl: BASE });
+    expect(project.project_id).toBe("9007199254740993");
+    expect(project.instance_id).toBe("9007199254740994");
+    expect(project.dblab_instance_id).toBe("9007199254740995");
+  });
 });
 
-describe("resolveProjectId (id-or-alias)", () => {
+describe("resolveJoeInstanceId (project id-or-alias → Joe instance)", () => {
+  const PROJECTS = [
+    { project_id: 12, alias: "main-db", name: "Main DB", joe_ready: true, instance_id: 3 },
+    { project_id: 13, alias: "no-joe", name: "No Joe", joe_ready: false, instance_id: null },
+  ];
+
   test("isNumericProjectRef distinguishes ids from aliases", () => {
     expect(isNumericProjectRef("12")).toBe(true);
     expect(isNumericProjectRef(" 12 ")).toBe(true);
@@ -202,329 +282,459 @@ describe("resolveProjectId (id-or-alias)", () => {
     expect(isNumericProjectRef("12a")).toBe(false);
   });
 
-  test("numeric ref resolves WITHOUT a projects lookup", async () => {
-    const captured = installFetch({ projects_list: () => json([]) });
-    const id = await resolveProjectId({ apiKey: "k", apiBaseUrl: BASE, project: "12" });
-    expect(id).toBe(12);
-    expect(captured.length).toBe(0);
+  test("a numeric project id resolves to the project's instance_id (lookup required)", async () => {
+    // Unlike a pure project-id resolver, the instance id only lives in the
+    // projects listing — a numeric ref must still hit projects_list.
+    const captured = installFetch({ projects_list: () => json(PROJECTS) });
+    const id = await resolveJoeInstanceId({ apiKey: "k", apiBaseUrl: BASE, project: "12" });
+    expect(id).toBe(3);
+    expect(captured.length).toBe(1);
   });
 
-  test("alias resolves via the projects list (case-insensitive)", async () => {
-    installFetch({
-      projects_list: () => json([{ id: 12, alias: "main-db", name: "Main DB", joe_ready: true }]),
-    });
-    const id = await resolveProjectId({ apiKey: "k", apiBaseUrl: BASE, project: "MAIN-DB" });
-    expect(id).toBe(12);
+  test("alias / name resolve case-insensitively to the same instance", async () => {
+    installFetch({ projects_list: () => json(PROJECTS) });
+    expect(await resolveJoeInstanceId({ apiKey: "k", apiBaseUrl: BASE, project: "MAIN-DB" })).toBe(3);
+    expect(await resolveJoeInstanceId({ apiKey: "k", apiBaseUrl: BASE, project: "main db" })).toBe(3);
   });
 
-  test("--project 12 ≡ --project main-db", async () => {
+  test("a 64-bit instance id survives as a string", async () => {
     installFetch({
-      projects_list: () => json([{ id: 12, alias: "main-db", name: "Main DB", joe_ready: true }]),
+      projects_list: () => json([{ project_id: 12, alias: "huge", instance_id: "9007199254740994" }]),
     });
-    const byId = await resolveProjectId({ apiKey: "k", apiBaseUrl: BASE, project: "12" });
-    const byAlias = await resolveProjectId({ apiKey: "k", apiBaseUrl: BASE, project: "main-db" });
-    expect(byId).toBe(byAlias);
+    expect(await resolveJoeInstanceId({ apiKey: "k", apiBaseUrl: BASE, project: "huge" }))
+      .toBe("9007199254740994");
   });
 
-  test("unknown alias throws", async () => {
-    installFetch({ projects_list: () => json([{ id: 12, alias: "main-db", name: "Main DB" }]) });
+  test("unknown ref throws with a 'pgai projects' hint", async () => {
+    installFetch({ projects_list: () => json(PROJECTS) });
     await expect(
-      resolveProjectId({ apiKey: "k", apiBaseUrl: BASE, project: "nope" })
-    ).rejects.toThrow(/Project not found for alias\/name 'nope'/);
+      resolveJoeInstanceId({ apiKey: "k", apiBaseUrl: BASE, project: "nope" })
+    ).rejects.toThrow(/Project not found for id\/alias\/name 'nope'/);
   });
 
-  test("label resolves via the projects list — same reference set as the DBLab resolver", async () => {
-    // dblab.ts `resolveDblabInstanceId` matches alias/name/LABEL; the Joe resolver
-    // must accept the same reference set, or `--project <label>` works for dblab
-    // verbs but fails for joe verbs on the very same project.
-    installFetch({
-      projects_list: () =>
-        json([{ id: 31, alias: "prod-db", name: "Prod", label: "Production EU", joe_ready: true }]),
-    });
-    const id = await resolveProjectId({ apiKey: "k", apiBaseUrl: BASE, project: "production eu" });
-    expect(id).toBe(31);
+  test("a project without a Joe instance throws", async () => {
+    installFetch({ projects_list: () => json(PROJECTS) });
+    await expect(
+      resolveJoeInstanceId({ apiKey: "k", apiBaseUrl: BASE, project: "no-joe" })
+    ).rejects.toThrow(/has no Joe instance/);
   });
 
-  test("empty project ref throws", async () => {
+  test("empty project ref throws before any network call", async () => {
+    const captured = installFetch({ projects_list: () => json(PROJECTS) });
     await expect(
-      resolveProjectId({ apiKey: "k", apiBaseUrl: BASE, project: "" })
+      resolveJoeInstanceId({ apiKey: "k", apiBaseUrl: BASE, project: "" })
     ).rejects.toThrow(/project is required/);
+    expect(captured.length).toBe(0);
   });
 });
 
-describe("computeIdempotencyKey", () => {
-  test("exec/explain keys are STABLE (deterministic) across calls", () => {
-    const a = computeIdempotencyKey("exec", 12, "create index on users (email)", null);
-    const b = computeIdempotencyKey("exec", 12, "create index on users (email)", null);
-    expect(a).toBe(b);
-    // A different statement diverges.
-    const c = computeIdempotencyKey("exec", 12, "create index on orders (id)", null);
-    expect(a).not.toBe(c);
+describe("buildJoeCommandText — the raw wire text per verb", () => {
+  test("SQL-carrying verbs prefix the verb, nothing else", () => {
+    expect(buildJoeCommandText("plan", { arg: "select * from users" })).toBe("plan select * from users");
+    expect(buildJoeCommandText("explain", { arg: "select 1" })).toBe("explain select 1");
+    expect(buildJoeCommandText("exec", { arg: "create index on users (email)" })).toBe("exec create index on users (email)");
+    expect(buildJoeCommandText("hypo", { arg: "create index on users (email)" })).toBe("hypo create index on users (email)");
+  });
+
+  test("bare verbs render as the verb alone", () => {
+    expect(buildJoeCommandText("activity")).toBe("activity");
+    expect(buildJoeCommandText("reset")).toBe("reset");
+  });
+
+  test("terminate renders `terminate <pid>` and rejects non-bare-digit pids", () => {
+    expect(buildJoeCommandText("terminate", { arg: "4711" })).toBe("terminate 4711");
+    for (const bad of ["0", "12x", "abc", "1.5", "0x10", "-5", "", "  "]) {
+      expect(() => buildJoeCommandText("terminate", { arg: bad })).toThrow("pid must be a positive integer");
+    }
+  });
+
+  test("describe defaults to \\d and honors an allowlisted --variant", () => {
+    expect(buildJoeCommandText("describe", { arg: "users" })).toBe("\\d users");
+    expect(buildJoeCommandText("describe", { arg: "users", variant: "\\d+" })).toBe("\\d+ users");
+    expect(buildJoeCommandText("describe", { arg: "users_pkey", variant: "\\di+" })).toBe("\\di+ users_pkey");
   });
 
-  test("plan keys are fresh per invocation", () => {
-    const a = computeIdempotencyKey("plan", 12, "select 1", null);
-    const b = computeIdempotencyKey("plan", 12, "select 1", null);
-    expect(a).not.toBe(b);
+  test("describe rejects a variant outside Joe's psql allowlist", () => {
+    for (const bad of ["\\dx", "\\copy", "d", "\\du"]) {
+      expect(() => buildJoeCommandText("describe", { arg: "users", variant: bad })).toThrow(/Unsupported describe variant/);
+    }
+    // The allowlist mirrors Joe's own dispatcher table.
+    expect([...DESCRIBE_VARIANTS]).toEqual(["\\d", "\\d+", "\\dt", "\\dt+", "\\di", "\\di+", "\\l", "\\l+", "\\dv", "\\dv+", "\\dm", "\\dm+"]);
+  });
+
+  test("empty required arguments throw", () => {
+    for (const verb of ["plan", "explain", "exec", "hypo"] as const) {
+      expect(() => buildJoeCommandText(verb, { arg: "  " })).toThrow(`${verb} requires an argument`);
+    }
+    expect(() => buildJoeCommandText("describe", { arg: "" })).toThrow("describe requires an object name");
+  });
+
+  test("JOE_COMMANDS is the Joe dispatcher verb set", () => {
+    const expected: JoeCommand[] = ["plan", "explain", "exec", "hypo", "activity", "terminate", "reset", "describe"];
+    expect([...JOE_COMMANDS]).toEqual(expected);
   });
 });
 
-describe("runCommand — submit-then-poll", () => {
-  test("polls until terminal then fetches the result", async () => {
-    let statusCalls = 0;
-    installFetch({
-      joe_command_submit: () => json({ command_id: "4711", session_id: "88", status: "queued" }),
-      joe_command_status: () => {
-        statusCalls += 1;
-        return json({ command_id: "4711", status: statusCalls < 2 ? "running" : "done", error: null });
+describe("runCommand — run-then-poll", () => {
+  test("polls the output until terminal (pending → pending → ok)", async () => {
+    let outputCalls = 0;
+    const captured = installFetch({
+      joe_command_run: () => json("4711"),
+      joe_command_output: () => {
+        outputCalls += 1;
+        if (outputCalls < 3) {
+          return json({ command_id: "4711", status: "pending" });
+        }
+        return json({ command_id: "4711", status: "ok", plan_text: "Index Scan", error: null });
       },
-      joe_command_result: () =>
-        json({ command_id: "4711", status: "done", plan_text: "Index Scan", plan_json: {}, error: null }),
     });
     const outcome = await runCommand({
       apiKey: "k",
       apiBaseUrl: BASE,
-      command: "plan",
-      projectId: 12,
-      sql: "select 1",
+      instanceId: 3,
+      command: "plan select 1",
       pollIntervalMs: 0,
       sleep: async () => {},
     });
-    expect(outcome.status).toBe("done");
+    expect(outcome.status).toBe("ok");
     expect(outcome.budgetExpired).toBe(false);
     expect(outcome.commandId).toBe("4711");
-    expect(outcome.sessionId).toBe("88");
-    expect(outcome.result?.plan_text).toBe("Index Scan");
-    expect(statusCalls).toBeGreaterThanOrEqual(2);
+    expect(outcome.output?.plan_text).toBe("Index Scan");
+    expect(outputCalls).toBe(3);
+    // Every poll carried the id as the string the run rpc returned.
+    for (const call of captured.slice(1)) {
+      expect(call.body).toEqual({ command_id: "4711" });
+    }
   });
 
-  test("budget expiry returns a resume handle without a result", async () => {
+  test("budget expiry returns a resume handle without an output", async () => {
     installFetch({
-      joe_command_submit: () => json({ command_id: "4712", session_id: "88", status: "queued" }),
-      joe_command_status: () => json({ command_id: "4712", status: "running", error: null }),
-      joe_command_result: () => json({ command_id: "4712", status: "done", error: null }),
+      joe_command_run: () => json("4712"),
+      joe_command_output: () => json({ command_id: "4712", status: "pending" }),
     });
     let clock = 1000;
     const outcome = await runCommand({
       apiKey: "k",
       apiBaseUrl: BASE,
-      command: "plan",
-      projectId: 12,
-      sql: "select 1",
+      instanceId: 3,
+      command: "plan select 1",
       budgetMs: 5,
       pollIntervalMs: 0,
       now: () => (clock += 10),
       sleep: async () => {},
     });
     expect(outcome.budgetExpired).toBe(true);
-    expect(outcome.status).toBe("running");
-    expect(outcome.result).toBeNull();
+    expect(outcome.status).toBe("pending");
+    expect(outcome.output).toBeNull();
     expect(outcome.commandId).toBe("4712");
   });
 
-  test("terminal error state fetches the result (error body)", async () => {
+  test("a stalled output request is aborted and returns a resume handle", async () => {
+    let calls = 0;
+    globalThis.fetch = mock((_url: string, options: RequestInit) => {
+      calls += 1;
+      if (calls === 1) {
+        return Promise.resolve(json("4713"));
+      }
+      return new Promise<Response>((_resolve, reject) => {
+        options.signal?.addEventListener("abort", () => reject(options.signal?.reason), { once: true });
+      });
+    }) as unknown as typeof fetch;
+
+    const outcome = await runCommand({
+      apiKey: "k",
+      apiBaseUrl: BASE,
+      instanceId: 3,
+      command: "plan select 1",
+      budgetMs: 10,
+      pollIntervalMs: 0,
+      sleep: async () => {},
+    });
+    expect(outcome).toMatchObject({
+      commandId: "4713",
+      status: "pending",
+      output: null,
+      budgetExpired: true,
+    });
+  });
+
+  test("a terminal error output is returned in full", async () => {
     installFetch({
-      joe_command_submit: () => json({ command_id: "5", session_id: null, status: "queued" }),
-      joe_command_status: () => json({ command_id: "5", status: "error", error: "PT500" }),
-      joe_command_result: () => json({ command_id: "5", status: "error", error: "boom", plan_json: {} }),
+      joe_command_run: () => json("5"),
+      joe_command_output: () => json({ command_id: "5", status: "error", error: "ERROR: relation \"nope\" does not exist" }),
     });
     const outcome = await runCommand({
       apiKey: "k",
       apiBaseUrl: BASE,
-      command: "plan",
-      projectId: 12,
-      sql: "select 1",
+      instanceId: 3,
+      command: "explain select * from nope",
       pollIntervalMs: 0,
       sleep: async () => {},
     });
     expect(outcome.status).toBe("error");
-    expect(outcome.result?.error).toBe("boom");
+    expect(outcome.budgetExpired).toBe(false);
+    expect(outcome.output?.error).toContain("does not exist");
   });
 
-  test("a NaN budget is clamped to the default budget (never an unbounded poll)", async () => {
-    // NaN survives `?? DEFAULT_BUDGET_MS` (it is neither null nor undefined), and
-    // `now() >= NaN` is always false — without a clamp the poll loop never exits.
-    // The status route trips a breaker well past the default-budget poll count so
-    // a regression fails fast instead of hanging the test runner.
-    let statusCalls = 0;
+  test("a transient 502 mid-poll never discards the id: keeps polling and recovers", async () => {
+    // startCommand already returned a valid command id; a proxy hiccup on ONE
+    // output poll must not throw it away — the loop retries within the budget.
+    let outputCalls = 0;
     installFetch({
-      joe_command_submit: () => json({ command_id: "9", session_id: null, status: "queued" }),
-      joe_command_status: () => {
-        statusCalls += 1;
-        if (statusCalls > 60) {
-          throw new Error("unbounded poll loop: NaN budget never expired");
+      joe_command_run: () => json("4714"),
+      joe_command_output: () => {
+        outputCalls += 1;
+        if (outputCalls === 1) {
+          return new Response("Bad Gateway", { status: 502 });
         }
-        return json({ command_id: "9", status: "running", error: null });
+        return json({ command_id: "4714", status: "ok", plan_text: "Index Scan", error: null });
       },
     });
-    let clock = 0;
     const outcome = await runCommand({
       apiKey: "k",
       apiBaseUrl: BASE,
-      command: "plan",
-      projectId: 12,
-      sql: "select 1",
-      budgetMs: Number.NaN,
+      instanceId: 3,
+      command: "plan select 1",
       pollIntervalMs: 0,
-      now: () => (clock += 1000), // 1 s per observation → passes the 25 s default budget in <30 polls
       sleep: async () => {},
     });
-    expect(outcome.budgetExpired).toBe(true);
-    expect(statusCalls).toBeLessThanOrEqual(60);
+    expect(outcome.status).toBe("ok");
+    expect(outcome.commandId).toBe("4714");
+    expect(outcome.output?.plan_text).toBe("Index Scan");
+    expect(outputCalls).toBe(2);
   });
 
-  test("exec submits a STABLE idempotency key", async () => {
-    const captured = installFetch({
-      joe_command_submit: () => json({ command_id: "6", session_id: "88", status: "queued" }),
-      joe_command_status: () => json({ command_id: "6", status: "done", error: null }),
-      joe_command_result: () => json({ command_id: "6", status: "done", row_count: 0, notices: ["CREATE INDEX"], error: null }),
+  test("a persistent 502 surfaces the id as a resume handle instead of throwing", async () => {
+    installFetch({
+      joe_command_run: () => json("4715"),
+      joe_command_output: () => new Response("Bad Gateway", { status: 502 }),
     });
-    await runCommand({
+    let clock = 0;
+    const outcome = await runCommand({
       apiKey: "k",
       apiBaseUrl: BASE,
-      command: "exec",
-      projectId: 12,
-      sql: "create index on users (email)",
+      instanceId: 3,
+      command: "plan select 1",
+      budgetMs: 25,
       pollIntervalMs: 0,
+      now: () => (clock += 10),
       sleep: async () => {},
     });
-    const expected = computeIdempotencyKey("exec", 12, "create index on users (email)", null);
-    expect(captured[0].body.idempotency_key).toBe(expected);
+    expect(outcome).toMatchObject({
+      commandId: "4715",
+      status: "pending",
+      output: null,
+      budgetExpired: true,
+    });
   });
-});
 
-describe("executeJoeCommand — session threading + persistence", () => {
-  test("auto-reuses the stored session id for the project", async () => {
-    const dir = tempDir();
-    writeStoredSessionId(12, "88", dir);
-    const captured = installFetch({
-      joe_command_submit: () => json({ command_id: "1", session_id: "88", status: "queued" }),
-      joe_command_status: () => json({ command_id: "1", status: "done", error: null }),
-      joe_command_result: () => json({ command_id: "1", status: "done", plan_text: "ok", error: null }),
+  test("a persistent 429 (rate limit) also surfaces the id as a resume handle", async () => {
+    installFetch({
+      joe_command_run: () => json("4716"),
+      joe_command_output: () => json({ message: "rate limited" }, 429),
     });
-    await executeJoeCommand({
+    let clock = 0;
+    const outcome = await runCommand({
       apiKey: "k",
       apiBaseUrl: BASE,
-      command: "plan",
-      project: "12",
-      sql: "select 1",
-      sessionDir: dir,
+      instanceId: 3,
+      command: "plan select 1",
+      budgetMs: 25,
       pollIntervalMs: 0,
+      now: () => (clock += 10),
       sleep: async () => {},
     });
-    expect(captured[0].body.session_id).toBe("88");
+    expect(outcome).toMatchObject({
+      commandId: "4716",
+      status: "pending",
+      output: null,
+      budgetExpired: true,
+    });
   });
 
-  test("persists the session id returned by submit", async () => {
-    const dir = tempDir();
+  test("a terminal 404 mid-poll DOES abort (polling on cannot succeed)", async () => {
     installFetch({
-      joe_command_submit: () => json({ command_id: "1", session_id: "99", status: "queued" }),
-      joe_command_status: () => json({ command_id: "1", status: "done", error: null }),
-      joe_command_result: () => json({ command_id: "1", status: "done", plan_text: "ok", error: null }),
+      joe_command_run: () => json("4717"),
+      joe_command_output: () => json({ code: "PT404", message: "Not found", details: "Specified command not found." }, 404),
     });
-    await executeJoeCommand({
+    await expect(
+      runCommand({
+        apiKey: "k",
+        apiBaseUrl: BASE,
+        instanceId: 3,
+        command: "plan select 1",
+        pollIntervalMs: 0,
+        sleep: async () => {},
+      })
+    ).rejects.toThrow(/Failed to fetch command output: HTTP 404/);
+  });
+
+  test("a NaN budget is clamped to the default budget (never an unbounded poll)", async () => {
+    // NaN survives `?? DEFAULT_BUDGET_MS` (it is neither null nor undefined), and
+    // `now() >= NaN` is always false — without a clamp the poll loop never exits.
+    // The output route trips a breaker well past the default-budget poll count so
+    // a regression fails fast instead of hanging the test runner.
+    let outputCalls = 0;
+    installFetch({
+      joe_command_run: () => json("9"),
+      joe_command_output: () => {
+        outputCalls += 1;
+        if (outputCalls > 60) {
+          throw new Error("unbounded poll loop: NaN budget never expired");
+        }
+        return json({ command_id: "9", status: "pending" });
+      },
+    });
+    let clock = 0;
+    const outcome = await runCommand({
       apiKey: "k",
       apiBaseUrl: BASE,
-      command: "plan",
-      project: "12",
-      sql: "select 1",
-      sessionDir: dir,
+      instanceId: 3,
+      command: "plan select 1",
+      budgetMs: Number.NaN,
       pollIntervalMs: 0,
+      now: () => (clock += 1000), // 1 s per observation → passes the 25 s default budget in <30 polls
       sleep: async () => {},
     });
-    expect(readStoredSessionId(12, dir)).toBe("99");
+    expect(outcome.budgetExpired).toBe(true);
+    expect(outputCalls).toBeLessThanOrEqual(60);
   });
+});
 
-  test("--new-session clears the stored session and submits null", async () => {
-    const dir = tempDir();
-    writeStoredSessionId(12, "88", dir);
+describe("executeJoeCommand — target → build → run", () => {
+  test("resolves an alias to the project's instance_id and sends the raw text", async () => {
     const captured = installFetch({
-      joe_command_submit: () => json({ command_id: "1", session_id: "100", status: "queued" }),
-      joe_command_status: () => json({ command_id: "1", status: "done", error: null }),
-      joe_command_result: () => json({ command_id: "1", status: "done", plan_text: "ok", error: null }),
+      projects_list: () => json([{ project_id: 12, alias: "main-db", name: "Main DB", joe_ready: true, instance_id: 3 }]),
+      joe_command_run: () => json("77"),
+      joe_command_output: () => json({ command_id: "77", status: "ok", plan_text: "ok", error: null }),
     });
-    await executeJoeCommand({
+    const outcome = await executeJoeCommand({
       apiKey: "k",
       apiBaseUrl: BASE,
       command: "plan",
-      project: "12",
-      sql: "select 1",
-      newSession: true,
-      sessionDir: dir,
+      project: "main-db",
+      input: { arg: "select 1" },
       pollIntervalMs: 0,
       sleep: async () => {},
     });
-    expect(captured[0].body.session_id).toBeNull();
-    // The freshly returned session id is persisted for the next command.
-    expect(readStoredSessionId(12, dir)).toBe("100");
+    expect(outcome.instanceId).toBe(3);
+    expect(outcome.commandText).toBe("plan select 1");
+    expect(outcome.status).toBe("ok");
+    const run = captured.find((c) => c.url.endsWith("/rpc/joe_command_run"));
+    expect(run?.body).toEqual({ instance_id: 3, command: "plan select 1" });
   });
 
-  test("explicit --session overrides the stored session", async () => {
-    const dir = tempDir();
-    writeStoredSessionId(12, "88", dir);
+  test("a bad verb argument fails BEFORE any network call", async () => {
     const captured = installFetch({
-      joe_command_submit: () => json({ command_id: "1", session_id: "77", status: "queued" }),
-      joe_command_status: () => json({ command_id: "1", status: "done", error: null }),
-      joe_command_result: () => json({ command_id: "1", status: "done", plan_text: "ok", error: null }),
+      projects_list: () => json([]),
+      joe_command_run: () => json("1"),
     });
-    await executeJoeCommand({
+    await expect(
+      executeJoeCommand({
+        apiKey: "k",
+        apiBaseUrl: BASE,
+        command: "terminate",
+        project: "12",
+        input: { arg: "12x" },
+      })
+    ).rejects.toThrow("pid must be a positive integer");
+    expect(captured.length).toBe(0);
+  });
+
+  test("a direct instanceId skips project resolution entirely", async () => {
+    // The v1 path: projects_list is not deployed, so the instance id is given
+    // directly and must go straight to joe_command_run — as the exact string,
+    // never resolved, never Number()ed.
+    const captured = installFetch({
+      joe_command_run: () => json("80"),
+      joe_command_output: () => json({ command_id: "80", status: "ok", response: "ok", error: null }),
+    });
+    const outcome = await executeJoeCommand({
       apiKey: "k",
       apiBaseUrl: BASE,
-      command: "plan",
-      project: "12",
-      sql: "select 1",
-      session: "77",
-      sessionDir: dir,
+      command: "explain",
+      instanceId: "9007199254740994001",
+      input: { arg: "select 1" },
       pollIntervalMs: 0,
       sleep: async () => {},
     });
-    expect(captured[0].body.session_id).toBe("77");
+    expect(outcome.status).toBe("ok");
+    expect(outcome.instanceId).toBe("9007199254740994001");
+    expect(captured.some((c) => c.url.endsWith("/rpc/projects_list"))).toBe(false);
+    const run = captured.find((c) => c.url.endsWith("/rpc/joe_command_run"));
+    expect(run?.body).toEqual({ instance_id: "9007199254740994001", command: "explain select 1" });
   });
 
-  test("resolves an alias to its project id before submitting", async () => {
-    const dir = tempDir();
+  test("instanceId wins over project when both are given (no projects_list call)", async () => {
     const captured = installFetch({
-      projects_list: () => json([{ id: 12, alias: "main-db", name: "Main DB", joe_ready: true }]),
-      joe_command_submit: () => json({ command_id: "1", session_id: "88", status: "queued" }),
-      joe_command_status: () => json({ command_id: "1", status: "done", error: null }),
-      joe_command_result: () => json({ command_id: "1", status: "done", plan_text: "ok", error: null }),
+      projects_list: () => json([{ project_id: 12, alias: "main-db", joe_ready: true, instance_id: 3 }]),
+      joe_command_run: () => json("81"),
+      joe_command_output: () => json({ command_id: "81", status: "ok", response: "ok", error: null }),
     });
-    const outcome = await executeJoeCommand({
+    await executeJoeCommand({
       apiKey: "k",
       apiBaseUrl: BASE,
-      command: "plan",
+      command: "reset",
       project: "main-db",
-      sql: "select 1",
-      sessionDir: dir,
+      instanceId: "7",
       pollIntervalMs: 0,
       sleep: async () => {},
     });
-    expect(outcome.projectId).toBe(12);
-    const submit = captured.find((c) => c.url.endsWith("/rpc/joe_command_submit"));
-    expect(submit?.body.project_id).toBe(12);
+    expect(captured.some((c) => c.url.endsWith("/rpc/projects_list"))).toBe(false);
+    const run = captured.find((c) => c.url.endsWith("/rpc/joe_command_run"));
+    expect(run?.body.instance_id).toBe("7");
   });
-});
 
-describe("session store helpers", () => {
-  test("write / read / clear round-trip", () => {
-    const dir = tempDir();
-    expect(readStoredSessionId(42, dir)).toBeNull();
-    writeStoredSessionId(42, "500", dir);
-    expect(readStoredSessionId(42, dir)).toBe("500");
-    expect(existsSync(resolve(dir, "joe-sessions.json"))).toBe(true);
-    clearStoredSessionId(42, dir);
-    expect(readStoredSessionId(42, dir)).toBeNull();
-  });
-
-  test("does not clobber other projects' sessions", () => {
-    const dir = tempDir();
-    writeStoredSessionId(1, "a", dir);
-    writeStoredSessionId(2, "b", dir);
-    clearStoredSessionId(1, dir);
-    expect(readStoredSessionId(1, dir)).toBeNull();
-    expect(readStoredSessionId(2, dir)).toBe("b");
-    const raw = JSON.parse(readFileSync(resolve(dir, "joe-sessions.json"), "utf8"));
-    expect(raw).toEqual({ "2": "b" });
+  test("a malformed instanceId is rejected before any network call", async () => {
+    const captured = installFetch({ joe_command_run: () => json("1") });
+    await expect(
+      executeJoeCommand({ apiKey: "k", apiBaseUrl: BASE, command: "reset", instanceId: "1; drop" })
+    ).rejects.toThrow("instanceId must be a numeric Joe instance id");
+    expect(captured.length).toBe(0);
+  });
+
+  test("neither instanceId nor project is a clear error before any network call", async () => {
+    const captured = installFetch({ joe_command_run: () => json("1") });
+    await expect(
+      executeJoeCommand({ apiKey: "k", apiBaseUrl: BASE, command: "reset" })
+    ).rejects.toThrow("either instanceId or project is required");
+    expect(captured.length).toBe(0);
+  });
+
+  test("the full output (plan_execution_*, stats, recommendations) reaches the outcome", async () => {
+    installFetch({
+      projects_list: () => json([{ project_id: 12, alias: "main-db", joe_ready: true, instance_id: 3 }]),
+      joe_command_run: () => json("78"),
+      joe_command_output: () =>
+        json({
+          command_id: "78",
+          status: "ok",
+          command: "explain",
+          query: "select 1",
+          queryid: "991",
+          plan_text: "Result",
+          plan_json: [{ Plan: { "Node Type": "Result" } }],
+          plan_execution_text: "Result (actual time=0.001..0.002)",
+          stats: "Time: 0.5 ms",
+          recommendations: "looks good",
+          error: null,
+        }),
+    });
+    const outcome = await executeJoeCommand({
+      apiKey: "k",
+      apiBaseUrl: BASE,
+      command: "explain",
+      project: "12",
+      input: { arg: "select 1" },
+      pollIntervalMs: 0,
+      sleep: async () => {},
+    });
+    expect(outcome.output).toMatchObject({
+      plan_execution_text: "Result (actual time=0.001..0.002)",
+      stats: "Time: 0.5 ms",
+      recommendations: "looks good",
+      queryid: "991",
+    });
   });
 });
 
@@ -540,319 +750,106 @@ describe("presentation helpers", () => {
     expect(flags[0]).toContain("Seq Scan on users");
   });
 
-  test("formatProjectsTable renders the brief's column header", () => {
-    const table = formatProjectsTable([
-      { project_id: 12, alias: "main-db", name: "Main DB", label: null, joe_ready: true, tunnel: true, instance_id: null, dblab_instance_id: 7 },
+  test("clientSidePlanFlags handles the EXPLAIN json array form the rpc returns", () => {
+    // plan_json is unwrapped server-side into EXPLAIN's native array shape:
+    // [{ "Plan": { … } }].
+    const flags = clientSidePlanFlags([
+      { Plan: { "Node Type": "Seq Scan", "Relation Name": "orders" } },
     ]);
-    const [header, row] = table.split("\n");
-    expect(header).toContain("PROJECT_ID");
-    expect(header).toContain("ALIAS");
-    expect(header).toContain("JOE");
-    expect(header).toContain("TUNNEL");
-    expect(row).toContain("12");
-    expect(row).toContain("main-db");
-    expect(row).toContain("ready");
-    expect(row).toContain("yes");
+    expect(flags.length).toBe(1);
+    expect(flags[0]).toContain("Seq Scan on orders");
+  });
+
+  test("clientSidePlanFlags handles empty, root, and multiple nested plans", () => {
+    expect(clientSidePlanFlags(null)).toEqual([]);
+    expect(clientSidePlanFlags({})).toEqual([]);
+    expect(clientSidePlanFlags({ "Node Type": "Seq Scan", "Relation Name": "root" })[0]).toContain("root");
+    expect(clientSidePlanFlags({
+      Plan: {
+        "Node Type": "Append",
+        Plans: [
+          { "Node Type": "Seq Scan", "Relation Name": "a" },
+          { "Node Type": "Seq Scan", "Relation Name": "b" },
+        ],
+      },
+    })).toHaveLength(2);
   });
 
-  test("formatJoeResult renders per-command bodies", () => {
-    const plan = formatJoeResult("plan", {
+  test("formatJoeOutput prints every present section of the uniform row", () => {
+    const output: JoeCommandOutput = {
       command_id: "1",
-      status: "done",
-      error: null,
+      status: "ok",
       plan_text: "Seq Scan on users",
-      plan_json: { Plan: { "Node Type": "Seq Scan", "Relation Name": "users" } },
-      queryid: "77",
-      plan_fingerprint: "a1",
-    });
-    expect(plan).toContain("Seq Scan on users");
-    expect(plan).toContain("⚑");
-
-    const exec = formatJoeResult("exec", {
-      command_id: "2",
-      status: "done",
+      plan_json: [{ Plan: { "Node Type": "Seq Scan", "Relation Name": "users" } }],
+      plan_execution_text: "Seq Scan on users (actual time=0.1..12.3)",
+      stats: "Time: 12.4 ms",
+      recommendations: ":warning: Seq Scan detected",
+      queryid: "7712349901234567890",
       error: null,
-      row_count: 0,
-      notices: ["CREATE INDEX"],
-    });
-    expect(exec).toContain("CREATE INDEX");
-
-    const terminate = formatJoeResult("terminate", {
-      command_id: "3",
-      status: "done",
-      error: null,
-      terminated: true,
-      pid: 4711,
-    });
-    expect(terminate).toContain("pid 4711");
-  });
-});
-
-describe("MCP tools", () => {
-  const ROOT = { apiKey: "k", apiBaseUrl: BASE };
-  const originalXdg = process.env.XDG_CONFIG_HOME;
-
-  function makeReq(name: string, args?: Record<string, unknown>): McpToolRequest {
-    return { params: { name, arguments: args } };
-  }
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch;
-    if (originalXdg === undefined) delete process.env.XDG_CONFIG_HOME;
-    else process.env.XDG_CONFIG_HOME = originalXdg;
-  });
-
-  test("joeToolDefinitions exposes every SPEC §5 name + list_projects", () => {
-    const names = joeToolDefinitions().map((t) => t.name);
-    expect(names).toEqual([
-      "plan_query",
-      "explain_query",
-      "exec_sql",
-      "hypo_index",
-      "activity",
-      "terminate_backend",
-      "reset_clone",
-      "describe",
-      "list_projects",
-    ]);
-    // Tool-name -> command map covers the 8 command tools.
-    expect(Object.keys(JOE_TOOL_TO_COMMAND).length).toBe(8);
-  });
-
-  test("exec_sql carries the stronger raw-data warning; plan/explain note the plan egress", () => {
-    const defs = joeToolDefinitions();
-    const exec = defs.find((t) => t.name === "exec_sql");
-    expect(exec?.description).toMatch(/REAL .*TABLE ROWS/i);
-    expect(exec?.description).toContain("LLM context");
-    const plan = defs.find((t) => t.name === "plan_query");
-    expect(plan?.description).toMatch(/plan-only/i);
-    expect(plan?.description).toMatch(/NEVER executes/i);
-    const explain = defs.find((t) => t.name === "explain_query");
-    expect(explain?.description).toMatch(/EXECUTES/);
-    expect(explain?.description).toMatch(/NOT raw SELECT result rows/i);
-  });
-
-  test("plan_query calls executeJoeCommand and returns the plan result", () => {
-    process.env.XDG_CONFIG_HOME = tempDir();
-    const captured = installFetch({
-      joe_command_submit: () => json({ command_id: "4711", session_id: "88", status: "queued" }),
-      joe_command_status: () => json({ command_id: "4711", status: "done", error: null }),
-      joe_command_result: () =>
-        json({ command_id: "4711", status: "done", plan_text: "Seq Scan on users", plan_json: {}, error: null }),
-    });
-    return handleToolCall(makeReq("plan_query", { sql: "select 1", project_id: "12" }), ROOT).then((res) => {
-      expect(res.isError).toBeFalsy();
-      const submit = captured.find((c) => c.url.endsWith("/rpc/joe_command_submit"));
-      expect(submit?.body.command).toBe("plan");
-      expect(submit?.body.project_id).toBe(12);
-      const payload = JSON.parse(res.content[0].text) as { status: string; result: { plan_text: string } };
-      expect(payload.status).toBe("done");
-      expect(payload.result.plan_text).toBe("Seq Scan on users");
-    });
-  });
-
-  test("exec_sql maps sql; requires it", async () => {
-    process.env.XDG_CONFIG_HOME = tempDir();
-    const captured = installFetch({
-      joe_command_submit: () => json({ command_id: "1", session_id: "88", status: "queued" }),
-      joe_command_status: () => json({ command_id: "1", status: "done", error: null }),
-      joe_command_result: () => json({ command_id: "1", command: "exec", status: "done", row_count: 0, notices: ["CREATE INDEX"], error: null }),
-    });
-    const ok = await handleToolCall(makeReq("exec_sql", { sql: "create index on users (email)", project_id: "12" }), ROOT);
-    expect(ok.isError).toBeFalsy();
-    const submit = captured.find((c) => c.url.endsWith("/rpc/joe_command_submit"));
-    expect(submit?.body.command).toBe("exec");
-
-    const missing = await handleToolCall(makeReq("exec_sql", { project_id: "12" }), ROOT);
-    expect(missing.isError).toBe(true);
-    expect(missing.content[0].text).toContain("sql is required");
-  });
-
-  test("hypo_index requires query and maps args.query", async () => {
-    process.env.XDG_CONFIG_HOME = tempDir();
-    const captured = installFetch({
-      joe_command_submit: () => json({ command_id: "1", session_id: "88", status: "queued" }),
-      joe_command_status: () => json({ command_id: "1", status: "done", error: null }),
-      joe_command_result: () => json({ command_id: "1", status: "done", hypo_used: true, hypo_plan: {}, error: null }),
-    });
-    const missing = await handleToolCall(makeReq("hypo_index", { sql: "create index on orders (customer_id)", project_id: "12" }), ROOT);
-    expect(missing.isError).toBe(true);
-    expect(missing.content[0].text).toContain("query is required");
-
-    const ok = await handleToolCall(
-      makeReq("hypo_index", { sql: "create index on orders (customer_id)", query: "select 1", project_id: "12" }),
-      ROOT
-    );
-    expect(ok.isError).toBeFalsy();
-    const submit = captured.find((c) => c.url.endsWith("/rpc/joe_command_submit"));
-    expect(submit?.body.command).toBe("hypo");
-    expect(submit?.body.args).toEqual({ query: "select 1" });
-  });
-
-  test("terminate_backend maps args.pid; describe maps args.object", async () => {
-    process.env.XDG_CONFIG_HOME = tempDir();
-    const captured = installFetch({
-      joe_command_submit: () => json({ command_id: "1", session_id: null, status: "queued" }),
-      joe_command_status: () => json({ command_id: "1", status: "done", error: null }),
-      joe_command_result: () => json({ command_id: "1", status: "done", terminated: true, pid: 4711, snapshot: {}, error: null }),
-    });
-    await handleToolCall(makeReq("terminate_backend", { pid: 4711, project_id: "12" }), ROOT);
-    let submit = captured.find((c) => c.url.endsWith("/rpc/joe_command_submit"));
-    expect(submit?.body.command).toBe("terminate");
-    expect(submit?.body.args).toEqual({ pid: 4711 });
-
-    captured.length = 0;
-    await handleToolCall(makeReq("describe", { object: "users", variant: "\\d+", project_id: "12" }), ROOT);
-    submit = captured.find((c) => c.url.endsWith("/rpc/joe_command_submit"));
-    expect(submit?.body.command).toBe("describe");
-    expect(submit?.body.args).toEqual({ object: "users", variant: "\\d+" });
-  });
-
-  test("terminate_backend rejects a non-integer / non-positive pid (no submit)", async () => {
-    // The CLI requires a bare-digits pid (^[0-9]+$); the MCP path must be as
-    // strict — `Number.isFinite` alone lets -5 / 1.5 / 0 through to a
-    // pg_terminate_backend against the wrong (or no) backend.
-    process.env.XDG_CONFIG_HOME = tempDir();
-    const captured = installFetch({
-      joe_command_submit: () => json({ command_id: "1", session_id: null, status: "queued" }),
-      joe_command_status: () => json({ command_id: "1", status: "done", error: null }),
-      joe_command_result: () => json({ command_id: "1", status: "done", terminated: true, pid: 4711, error: null }),
-    });
-    for (const bad of [-5, 1.5, 0, "12x", "1.5", "-5", "abc", Number.NaN]) {
-      const res = await handleToolCall(makeReq("terminate_backend", { pid: bad, project_id: "12" }), ROOT);
-      expect(res.isError).toBe(true);
-      expect(res.content[0].text).toContain("pid");
-    }
-    expect(captured.some((c) => c.url.endsWith("/rpc/joe_command_submit"))).toBe(false);
-
-    // A strict positive integer — as a number or a bare-digits string — still submits.
-    const ok = await handleToolCall(makeReq("terminate_backend", { pid: "4711", project_id: "12" }), ROOT);
-    expect(ok.isError).toBeFalsy();
-    const submit = captured.find((c) => c.url.endsWith("/rpc/joe_command_submit"));
-    expect(submit?.body.args).toEqual({ pid: 4711 });
-  });
-
-  test("list_projects tool returns the normalized projects", async () => {
-    process.env.XDG_CONFIG_HOME = tempDir();
-    installFetch({
-      projects_list: () => json([{ id: 12, alias: "main-db", name: "Main DB", joe_ready: true, tunnel: true }]),
-    });
-    const res = await handleToolCall(makeReq("list_projects", {}), ROOT);
-    expect(res.isError).toBeFalsy();
-    const projects = JSON.parse(res.content[0].text) as Array<{ project_id: number; alias: string }>;
-    expect(projects[0].project_id).toBe(12);
-    expect(projects[0].alias).toBe("main-db");
-  });
-
-  test("resolves an alias project_id before submitting", async () => {
-    process.env.XDG_CONFIG_HOME = tempDir();
-    const captured = installFetch({
-      projects_list: () => json([{ id: 12, alias: "main-db", name: "Main DB", joe_ready: true }]),
-      joe_command_submit: () => json({ command_id: "1", session_id: "88", status: "queued" }),
-      joe_command_status: () => json({ command_id: "1", status: "done", error: null }),
-      joe_command_result: () => json({ command_id: "1", status: "done", plan_text: "ok", error: null }),
-    });
-    await handleToolCall(makeReq("plan_query", { sql: "select 1", project_id: "main-db" }), ROOT);
-    const submit = captured.find((c) => c.url.endsWith("/rpc/joe_command_submit"));
-    expect(submit?.body.project_id).toBe(12);
-  });
-
-  test("ai_enabled=false PT403 surfaces as an MCP error", async () => {
-    process.env.XDG_CONFIG_HOME = tempDir();
-    installFetch({
-      joe_command_submit: () =>
-        json({ message: "AI features disabled for this org — enable in AI Assistant Settings" }, 403),
-    });
-    const res = await handleToolCall(makeReq("plan_query", { sql: "select 1", project_id: "12" }), ROOT);
-    expect(res.isError).toBe(true);
-    expect(res.content[0].text).toContain("AI features disabled for this org");
+    };
+    const text = formatJoeOutput(output);
+    expect(text).toContain("plan:");
+    expect(text).toContain("Seq Scan on users");
+    expect(text).toContain("⚑");
+    expect(text).toContain("execution plan (EXPLAIN ANALYZE):");
+    expect(text).toContain("stats:");
+    expect(text).toContain("Time: 12.4 ms");
+    expect(text).toContain("recommendations:");
+    expect(text).toContain("(queryid 7712349901234567890)");
   });
 
-  test("missing project_id is an error", async () => {
-    process.env.XDG_CONFIG_HOME = tempDir();
-    const res = await handleToolCall(makeReq("plan_query", { sql: "select 1" }), ROOT);
-    expect(res.isError).toBe(true);
-    expect(res.content[0].text).toContain("project_id is required");
+  test("formatJoeOutput prints a bare response (exec/describe/activity) without labels", () => {
+    const text = formatJoeOutput({ command_id: "2", status: "ok", response: "CREATE INDEX", error: null });
+    expect(text).toBe("CREATE INDEX");
   });
 
-  test("sanitizeBudgetMs only accepts finite numbers (mirrors the CLI --budget guard)", () => {
-    // A non-finite budget must fall back to undefined → runCommand's default —
-    // NaN would survive `?? DEFAULT_BUDGET_MS` and make the poll loop unbounded.
-    expect(sanitizeBudgetMs(undefined)).toBeUndefined();
-    expect(sanitizeBudgetMs(null)).toBeUndefined();
-    expect(sanitizeBudgetMs("abc")).toBeUndefined();
-    expect(sanitizeBudgetMs(Number.NaN)).toBeUndefined();
-    expect(sanitizeBudgetMs(Infinity)).toBeUndefined();
-    expect(sanitizeBudgetMs({})).toBeUndefined();
-    expect(sanitizeBudgetMs(5000)).toBe(5000);
-    expect(sanitizeBudgetMs("5000")).toBe(5000);
-    expect(sanitizeBudgetMs(0)).toBe(0);
+  test("formatJoeOutput renders nothing for an empty row", () => {
+    expect(formatJoeOutput({ command_id: "3", status: "ok", error: null })).toBe("");
   });
 
-  test("timeout_ms: 0 expires immediately with a resume handle (budget mapped through)", async () => {
-    process.env.XDG_CONFIG_HOME = tempDir();
-    installFetch({
-      joe_command_submit: () => json({ command_id: "31", session_id: "88", status: "queued" }),
-      joe_command_status: () => json({ command_id: "31", status: "running", error: null }),
-    });
-    const res = await handleToolCall(
-      makeReq("plan_query", { sql: "select 1", project_id: "12", timeout_ms: 0 }),
-      ROOT
-    );
-    // Budget expiry is NOT an error — the caller gets a resume handle.
-    expect(res.isError).toBeFalsy();
-    const payload = JSON.parse(res.content[0].text) as {
-      budget_expired: boolean;
-      resume?: string;
-      command_id: string;
-    };
-    expect(payload.budget_expired).toBe(true);
-    expect(payload.resume).toBe("pgai joe result 31");
+  test("formatProjectsTable renders the fixed-width columns", () => {
+    const table = formatProjectsTable([
+      { project_id: 12, alias: "main-db", name: "Main DB", joe_ready: true, tunnel: true, instance_id: 3, dblab_instance_id: 7 },
+    ]);
+    const [header, row] = table.split("\n");
+    expect(header).toContain("PROJECT_ID");
+    expect(header).toContain("ALIAS");
+    expect(header).toContain("JOE");
+    expect(header).toContain("TUNNEL");
+    expect(row).toContain("12");
+    expect(row).toContain("main-db");
+    expect(row).toContain("ready");
+    expect(row).toContain("yes");
   });
 });
 
 describe("--debug credential redaction (joe rpc surface)", () => {
   test("response bodies have password-named fields redacted before logging", async () => {
-    // `--debug` (and the MCP caller-controlled debug flag) writes the raw
-    // response body to stderr; any credential-shaped field must be masked the
-    // same way the access-token header already is.
+    // `--debug` writes the raw response body to stderr; any credential-shaped
+    // field must be masked the same way the access-token header already is.
     const spy = spyOn(console, "error").mockImplementation(() => {});
     try {
       installFetch({
-        joe_command_result: () =>
+        joe_command_output: () =>
           json({
             command_id: "1",
             command: "exec",
-            status: "done",
+            status: "ok",
             error: null,
-            result_rows: [{ usename: "app", password: "row-secret-xyz" }],
+            response: "ok",
+            stats: null,
+            plan_text: null,
+            password: "row-secret-xyz",
           }),
       });
-      await getCommandResult({ apiKey: "k", apiBaseUrl: BASE, commandId: "1", debug: true });
+      await getCommandOutput({ apiKey: "k", apiBaseUrl: BASE, commandId: "1", debug: true });
       const logged = spy.mock.calls.map((c) => c.map(String).join(" ")).join("\n");
       expect(logged).toContain("Debug: Response body");
       expect(logged).not.toContain("row-secret-xyz");
       // The rest of the body still logs (redaction, not suppression).
-      expect(logged).toContain("usename");
+      expect(logged).toContain("command_id");
     } finally {
       spy.mockRestore();
     }
   });
 });
-
-describe("command set", () => {
-  test("JOE_COMMANDS is the SPEC command set", () => {
-    const expected: JoeCommand[] = ["plan", "explain", "exec", "hypo", "activity", "terminate", "reset", "describe"];
-    expect([...JOE_COMMANDS]).toEqual(expected);
-  });
-
-  test("each command submits with its fixed command name", async () => {
-    for (const command of JOE_COMMANDS) {
-      const captured = installFetch({
-        joe_command_submit: () => json({ command_id: "1", session_id: null, status: "queued" as JoeStatus }),
-      });
-      await submitCommand({ apiKey: "k", apiBaseUrl: BASE, command, projectId: 12, idempotencyKey: "x" });
-      expect(captured[0].body.command).toBe(command);
-    }
-  });
-});