@linkedclaw/cli 0.1.3 → 0.1.5

package/src/converge/types.ts

@@ -0,0 +1,91 @@
+export interface RunMeta {
+  run_id: string;
+  source_debate_id: string;
+  pa_agent_id: string;
+  target_corpus: string;
+  owner_role: "a" | "b";
+}
+
+export interface RunWorkspace {
+  runId: string;
+  sourceDebateId: string;
+  paAgentId: string;
+  targetCorpus: string;
+  stagingDir: string;
+}
+
+export interface DebateRecord {
+  debate_id: string;
+  agent_a_id: string;
+  agent_b_id: string;
+  commons_log_id: string;
+  counterparty_user_id: string | null;
+  status: string;
+  topic?: string;
+}
+
+export interface CommonsLogEvent {
+  seq: number;
+  event_type: string;
+  payload: Record<string, unknown>;
+  appended_at: string;
+  signed_by: string;
+  signature_hash?: string;
+}
+
+export interface AgentListing {
+  agent_id: string;
+  slug: string;
+  capabilities: string[];
+}
+
+export interface MandateRecord {
+  mandate_id: string;
+  principal_agent_id: string;
+  delegate_agent_id: string;
+  scope: string[];
+  expires_at: string | null;
+  revoked_at?: string | null;
+}
+
+export interface RunStateSummary {
+  run_id: string;
+  source_debate_id: string;
+  started_at: string | null;
+  owner_b_accepted: boolean;
+  cruxes: Array<{
+    crux_id: string;
+    latest_sub_debate_id: string | null;
+    sub_debate_chain: string[];
+    outcome: string | null;
+    bilateral_mandate_intact: boolean | null;
+  }>;
+  terminal_emitted: boolean;
+}
+
+export type ConvergenceDecisionAction = "accept" | "reject" | "attest";
+
+export type ConvergenceAttestation =
+  | "bilateral_convergence"
+  | "user_attested_with_network_context"
+  | "user_attested_no_dialog";
+
+export interface CruxDecisionRequest {
+  convergence_map_generation_id: string;
+  source_crux_map_hash: string;
+  latest_sub_debate_id: string | null;
+  terminal_outcome: "converged" | "partial_overlap" | "needs_input" | "irreconcilable" | "already_aligned";
+  bilateral_mandate_intact: boolean;
+  attestation: ConvergenceAttestation;
+  synthesis_edited: boolean;
+  pa_body_hash: string;
+  accepted_body_hash: string;
+  synthesis_text: string;
+  citations_a: Array<Record<string, unknown>>;
+  citations_b: Array<Record<string, unknown>>;
+  user_message?: string | null;
+}
+
+export interface CruxDecisionResponse {
+  event_id: string;
+}

package/src/converge/workspace.ts

@@ -0,0 +1,92 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { load as yamlLoad, dump as yamlDump } from "js-yaml";
+import { LinkedClawError } from "../errors.js";
+import type { RunMeta, RunWorkspace } from "./types.js";
+
+export interface ResolveOpts {
+  runId?: string;
+  stagingDir?: string;
+  targetCorpus?: string;
+  cwd?: string;
+}
+
+const META_FILENAME = ".run-meta.yaml";
+
+export function readRunMeta(stagingDir: string): RunMeta | null {
+  const metaPath = join(stagingDir, META_FILENAME);
+  if (!existsSync(metaPath)) return null;
+  return yamlLoad(readFileSync(metaPath, "utf8")) as RunMeta;
+}
+
+export function writeRunMeta(stagingDir: string, meta: RunMeta): void {
+  mkdirSync(stagingDir, { recursive: true });
+  writeFileSync(join(stagingDir, META_FILENAME), yamlDump(meta), "utf8");
+}
+
+function searchUpward(startDir: string, maxLevels = 5): string | null {
+  let dir = startDir;
+  for (let i = 0; i < maxLevels; i++) {
+    if (existsSync(join(dir, META_FILENAME))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+  return null;
+}
+
+export async function resolveWorkspace(opts: ResolveOpts): Promise<RunWorkspace> {
+  const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
+
+  let stagingDir: string | undefined;
+  let meta: RunMeta | null = null;
+
+  if (opts.stagingDir) {
+    stagingDir = isAbsolute(opts.stagingDir) ? opts.stagingDir : resolve(cwd, opts.stagingDir);
+    meta = readRunMeta(stagingDir);
+    if (!meta) {
+      throw new LinkedClawError(
+        "meta_not_found",
+        `No ${META_FILENAME} found in --staging-dir: ${stagingDir}`,
+      );
+    }
+  } else {
+    const found = searchUpward(cwd);
+    if (found) {
+      stagingDir = found;
+      meta = readRunMeta(found)!;
+    }
+  }
+
+  if (!meta) {
+    if (opts.runId) {
+      throw new LinkedClawError(
+        "meta_not_found",
+        `--run-id given but no ${META_FILENAME} found (searched upward from ${cwd}). Provide --staging-dir to locate the run workspace.`,
+      );
+    }
+    throw new LinkedClawError(
+      "meta_not_found",
+      `No ${META_FILENAME} found (searched upward from ${cwd}). Run 'lc converge run <debate_id>' first.`,
+    );
+  }
+
+  if (opts.runId && opts.runId !== meta.run_id) {
+    throw new LinkedClawError(
+      "run_id_mismatch",
+      `--run-id ${opts.runId} does not match run_id ${meta.run_id} in ${META_FILENAME}`,
+    );
+  }
+
+  const targetCorpus = isAbsolute(meta.target_corpus)
+    ? meta.target_corpus
+    : resolve(stagingDir!, meta.target_corpus);
+
+  return {
+    runId: meta.run_id,
+    sourceDebateId: meta.source_debate_id,
+    paAgentId: meta.pa_agent_id,
+    targetCorpus,
+    stagingDir: stagingDir!,
+  };
+}

package/src/handlers/subprocess.ts

@@ -15,10 +15,10 @@ import type { Readable, Writable } from "node:stream";
 import { randomUUID } from "node:crypto";
 import { createInterface } from "node:readline";
 import type {
-  BroadcastExecuteEvent,
-  BroadcastExecuteResult,
-  BroadcastOfferDecision,
-  BroadcastOfferEvent,
+  GigTaskExecuteEvent,
+  GigTaskExecuteResult,
+  GigTaskOfferDecision,
+  GigTaskOfferEvent,
   InvokeEvent,
   InvokeHandlerResult,
   ProviderHandler,
@@ -100,12 +100,12 @@ export class SubprocessHandler implements ProviderHandler {
     return this.request<InvokeHandlerResult>(evt);
   }
 
-  async onBroadcastOffer(evt: BroadcastOfferEvent): Promise<BroadcastOfferDecision> {
-    return this.request<BroadcastOfferDecision>(evt);
+  async onGigTaskOffer(evt: GigTaskOfferEvent): Promise<GigTaskOfferDecision> {
+    return this.request<GigTaskOfferDecision>(evt);
   }
 
-  async onBroadcastExecute(evt: BroadcastExecuteEvent): Promise<BroadcastExecuteResult> {
-    return this.request<BroadcastExecuteResult>(evt);
+  async onGigTaskExecute(evt: GigTaskExecuteEvent): Promise<GigTaskExecuteResult> {
+    return this.request<GigTaskExecuteResult>(evt);
   }
 
   // ───── shutdown ─────

package/src/types.ts

@@ -52,7 +52,7 @@ export interface TaskManifest {
   [key: string]: unknown;
 }
 
-export interface CreateBroadcastRequest {
+export interface CreateGigTaskRequest {
   capability: string;
   instruction: string;
   target_providers: number;
@@ -67,12 +67,12 @@ export interface CreateBroadcastRequest {
   referred_by?: EntityId;
 }
 
-export interface AcceptBroadcastRequest {
+export interface AcceptGigTaskRequest {
   agent_id: EntityId;
   slot_key?: string | null;
 }
 
-export interface BroadcastSubmitRequest {
+export interface GigTaskSubmitRequest {
   result_data: string;
   result_payload?: Record<string, unknown> | null;
   proof?: Array<{ type: string; value: string; label?: string }> | null;
@@ -81,8 +81,8 @@ export interface BroadcastSubmitRequest {
 // Re-export provider-runtime types needed by commands
 export type {
   ProviderHandler,
-  BroadcastOfferDecision,
-  BroadcastExecuteResult,
+  GigTaskOfferDecision,
+  GigTaskExecuteResult,
   InvokeHandlerResult,
   SessionAcceptDecision,
   SessionReply,

package/test/agent-help.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from "vitest";
+import { spawnSync } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { chmodSync, existsSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+
+const spawnMock = vi.hoisted(() => vi.fn());
+
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return { ...actual, spawn: spawnMock };
+});
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BIN = path.resolve(__dirname, "../dist/bin.js");
+const ORIGINAL_CONFIG_ENV = process.env.LINKEDCLAW_OWNER_AGENT_CONFIG;
+const ORIGINAL_EXIT_CODE = process.exitCode;
+
+type FakeChild = EventEmitter & {
+  killed: boolean;
+  kill: ReturnType<typeof vi.fn>;
+};
+
+let activeChild: FakeChild | undefined;
+
+beforeAll(() => {
+  if (!existsSync(BIN)) {
+    throw new Error(`bin not built — run 'pnpm --filter @linkedclaw/cli build' first (${BIN})`);
+  }
+});
+
+beforeEach(() => {
+  spawnMock.mockReset();
+  delete process.env.LINKEDCLAW_OWNER_AGENT_CONFIG;
+  activeChild = undefined;
+});
+
+afterEach(() => {
+  if (activeChild !== undefined) {
+    activeChild.emit("exit", 0, null);
+    activeChild = undefined;
+  }
+  if (ORIGINAL_CONFIG_ENV === undefined) {
+    delete process.env.LINKEDCLAW_OWNER_AGENT_CONFIG;
+  } else {
+    process.env.LINKEDCLAW_OWNER_AGENT_CONFIG = ORIGINAL_CONFIG_ENV;
+  }
+  process.exitCode = ORIGINAL_EXIT_CODE;
+});
+
+function run(args: string[]): { code: number | null; stdout: string; stderr: string } {
+  const r = spawnSync("node", [BIN, ...args], { encoding: "utf8" });
+  return { code: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+function makeFakeChild(): FakeChild {
+  const child = new EventEmitter() as FakeChild;
+  child.killed = false;
+  child.kill = vi.fn(() => true);
+  activeChild = child;
+  return child;
+}
+
+function makeFakePython(): string {
+  const dir = mkdtempSync(path.join(tmpdir(), "linkedclaw-agent-cli-"));
+  const fakePython = path.join(dir, "fake-python");
+  writeFileSync(fakePython, "#!/bin/sh\nexit 0\n", "utf8");
+  chmodSync(fakePython, 0o700);
+  return fakePython;
+}
+
+async function runHiddenAgent(args: string[]): Promise<FakeChild> {
+  const child = makeFakeChild();
+  spawnMock.mockReturnValueOnce(child);
+  const program = new Command();
+  program.exitOverride();
+  const { registerAgentCommands } = await import("../src/commands/agent.js");
+  registerAgentCommands(program);
+  await program.parseAsync(["node", "cli", "agent", "run", ...args]);
+  return child;
+}
+
+async function runHiddenRotate(args: string[]): Promise<FakeChild | undefined> {
+  const child = makeFakeChild();
+  spawnMock.mockReturnValueOnce(child);
+  const program = new Command();
+  program.exitOverride();
+  const { registerAgentCommands } = await import("../src/commands/agent.js");
+  registerAgentCommands(program);
+  await program.parseAsync(["node", "cli", "agent", "rotate-mandate", ...args]);
+  return process.exitCode === 1 ? undefined : child;
+}
+
+describe("agent command packaging", () => {
+  it("exposes the owner-agent run command in the npm CLI", () => {
+    const top = run(["--help"]);
+    expect(top.code).toBe(0);
+    expect(top.stdout).toContain("agent");
+
+    const agent = run(["agent", "--help"]);
+    expect(agent.code).toBe(0);
+    expect(agent.stdout).toContain("run");
+    expect(agent.stdout).toContain("rotate-mandate");
+
+    const runHelp = run(["agent", "run", "--help"]);
+    expect(runHelp.code).toBe(0);
+    expect(runHelp.stdout).toContain("--config");
+    expect(runHelp.stdout).toContain("--watch");
+    expect(runHelp.stdout).toContain("--once");
+    expect(runHelp.stdout).toContain("--python-command");
+
+    const rotateHelp = run(["agent", "rotate-mandate", "--help"]);
+    expect(rotateHelp.code).toBe(0);
+    expect(rotateHelp.stdout).toContain("--config");
+    expect(rotateHelp.stdout).toContain("--old-mandate-id");
+    expect(rotateHelp.stdout).toContain("--expires-at");
+    expect(rotateHelp.stdout).toContain("--python-command");
+  });
+
+  it("reads LINKEDCLAW_OWNER_AGENT_CONFIG when --config is omitted", async () => {
+    const configPath = path.join(mkdtempSync(path.join(tmpdir(), "linkedclaw-agent-cli-")), "config.yaml");
+    const fakePython = makeFakePython();
+    writeFileSync(configPath, "agent_id: ag_owner\n", "utf8");
+    process.env.LINKEDCLAW_OWNER_AGENT_CONFIG = configPath;
+
+    await runHiddenAgent(["--watch", "debate_1:clg_1", "--once", "--python-command", fakePython]);
+
+    expect(spawnMock).toHaveBeenCalledWith(fakePython, [
+      "-m",
+      "linkedclaw.owner_agent.cli",
+      "run",
+      "--config",
+      configPath,
+      "--watch",
+      "debate_1:clg_1",
+      "--once",
+    ], { stdio: "inherit" });
+  });
+
+  it("forwards SIGTERM and SIGINT to the Python child", async () => {
+    const fakePython = makeFakePython();
+    const sigtermChild = await runHiddenAgent(["--once", "--python-command", fakePython]);
+
+    process.emit("SIGTERM");
+    expect(sigtermChild.kill).toHaveBeenCalledWith("SIGTERM");
+    sigtermChild.emit("exit", 0, null);
+    activeChild = undefined;
+
+    const sigintChild = await runHiddenAgent(["--once", "--python-command", fakePython]);
+    process.emit("SIGINT");
+    expect(sigintChild.kill).toHaveBeenCalledWith("SIGINT");
+  });
+
+  it("rotates mandates with env config and forwards optional flags", async () => {
+    const configPath = path.join(mkdtempSync(path.join(tmpdir(), "linkedclaw-agent-cli-")), "config.yaml");
+    const fakePython = makeFakePython();
+    writeFileSync(configPath, "agent_id: ag_owner\n", "utf8");
+    process.env.LINKEDCLAW_OWNER_AGENT_CONFIG = configPath;
+
+    await runHiddenRotate([
+      "--old-mandate-id",
+      "man_old",
+      "--expires-at",
+      "2026-05-04T00:00:00Z",
+      "--python-command",
+      fakePython,
+    ]);
+
+    expect(spawnMock).toHaveBeenCalledWith(fakePython, [
+      "-m",
+      "linkedclaw.owner_agent.cli",
+      "rotate-mandate",
+      "--config",
+      configPath,
+      "--old-mandate-id",
+      "man_old",
+      "--expires-at",
+      "2026-05-04T00:00:00Z",
+    ], { stdio: "inherit" });
+  });
+
+  it("rejects invalid rotate mandate options as JSON", async () => {
+    const configPath = path.join(mkdtempSync(path.join(tmpdir(), "linkedclaw-agent-cli-")), "config.yaml");
+    const fakePython = makeFakePython();
+    writeFileSync(configPath, "agent_id: ag_owner\n", "utf8");
+    const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    await runHiddenRotate([
+      "--config",
+      configPath,
+      "--old-mandate-id",
+      "",
+      "--python-command",
+      fakePython,
+    ]);
+
+    expect(spawnMock).not.toHaveBeenCalled();
+    expect(stderrSpy).toHaveBeenCalled();
+    const payload = JSON.parse(String(stderrSpy.mock.calls[0][0]));
+    expect(payload.error).toBe("invalid_agent_rotate_mandate_option");
+    expect(payload.message).toContain("--old-mandate-id");
+    stderrSpy.mockRestore();
+  });
+});

package/test/arena-api.test.ts

@@ -0,0 +1,211 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ApiError } from "../src/errors.js";
+import { makeArenaApi } from "../src/arena/api.js";
+
+function jsonResponse(body: unknown, init: { ok?: boolean; status?: number } = {}) {
+  return {
+    ok: init.ok ?? true,
+    status: init.status ?? 200,
+    json: vi.fn(async () => body),
+  } as any;
+}
+
+describe("makeArenaApi", () => {
+  const fetchMock = vi.fn();
+
+  beforeEach(() => {
+    fetchMock.mockResolvedValue(jsonResponse({ ok: true }));
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("register posts to the contestant registration route", async () => {
+    const api = makeArenaApi("http://services.test/", "k");
+    await api.register({
+      contestant_agent_id: "agt_1",
+      mandate_id: "mand_1",
+      category: { topic: "code", subtopic: "rust" },
+    });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://services.test/api/v1/arena/contestants/register",
+      expect.objectContaining({ method: "POST" }),
+    );
+  });
+
+  it("createTournamentArena posts the exact manifest with idempotency header", async () => {
+    const api = makeArenaApi("http://services.test/", "k");
+    const manifest = {
+      mode: "tournament" as const,
+      category: { topic: "code", subtopic: "rust" },
+      config: {
+        bracket_shape: "single_elim",
+        child_mode: "task_submission",
+        advancement_rule: "top_k(1)",
+        bracket_size: 4,
+        seeding: "unseeded",
+        child_config: { prompt: "ship a patch" },
+      },
+    };
+    await api.createTournamentArena(manifest, { idempotencyKey: "idem_123" });
+    const [, init] = fetchMock.mock.calls[0];
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://services.test/api/v1/arena/arenas",
+      expect.objectContaining({ method: "POST" }),
+    );
+    expect(init.headers).toMatchObject({
+      Authorization: "Bearer k",
+      "X-CSRF-Token": "k",
+      "Idempotency-Key": "idem_123",
+    });
+    expect(JSON.parse(init.body)).toEqual(manifest);
+  });
+
+  it("offers uses GET and accepts pending matches", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({
+      offers: [],
+      pending_matches: [{ match_id: "amch_123", prompt: "ship it" }],
+    }));
+    const api = makeArenaApi("http://services.test", "k");
+    const response = await api.listOffers();
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://services.test/api/v1/arena/offers",
+      expect.objectContaining({ method: "GET" }),
+    );
+    expect(response.pending_matches?.[0].match_id).toBe("amch_123");
+  });
+
+  it("acceptOffer posts to the offer accept route", async () => {
+    const api = makeArenaApi("http://services.test", "k");
+    await api.acceptOffer("aoff_123");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://services.test/api/v1/arena/offers/aoff_123/accept",
+      expect.objectContaining({ method: "POST" }),
+    );
+  });
+
+  it("submit posts to the submissions route and strips only client-only submission_hash", async () => {
+    const api = makeArenaApi("http://services.test", "k");
+    await api.submit("arn_123", {
+      offer_id: "aoff_123",
+      raw_content: "hello",
+      match_id: "amch_123",
+      seq: 1,
+      submission_hash: "sha256:" + "a".repeat(64),
+    });
+    const [, init] = fetchMock.mock.calls[0];
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://services.test/api/v1/arena/arenas/arn_123/submissions",
+      expect.objectContaining({ method: "POST" }),
+    );
+    expect(JSON.parse(init.body)).toEqual({
+      offer_id: "aoff_123",
+      raw_content: "hello",
+      match_id: "amch_123",
+      seq: 1,
+    });
+  });
+
+  it("commitJuror posts to the juror commit route with the exact body", async () => {
+    const api = makeArenaApi("http://services.test", "k");
+    await api.commitJuror("arn_123", {
+      juror_agent_id: "agt_juror",
+      mandate_id: "mnd_123",
+    });
+    const [, init] = fetchMock.mock.calls[0];
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://services.test/api/v1/arena/arenas/arn_123/jurors/commit",
+      expect.objectContaining({ method: "POST" }),
+    );
+    expect(JSON.parse(init.body)).toEqual({
+      juror_agent_id: "agt_juror",
+      mandate_id: "mnd_123",
+    });
+  });
+
+  it("voteTask posts to the task juror vote route with the exact body", async () => {
+    const api = makeArenaApi("http://services.test", "k");
+    await api.voteTask("arn_123", {
+      submission_id: "asub_123",
+      score: 0.75,
+      rationale_ref: "note://1",
+    });
+    const [, init] = fetchMock.mock.calls[0];
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://services.test/api/v1/arena/arenas/arn_123/juror-votes",
+      expect.objectContaining({ method: "POST" }),
+    );
+    expect(JSON.parse(init.body)).toEqual({
+      submission_id: "asub_123",
+      score: 0.75,
+      rationale_ref: "note://1",
+    });
+  });
+
+  it("voteMatch posts to the match juror vote route with the exact body", async () => {
+    const api = makeArenaApi("http://services.test", "k");
+    await api.voteMatch("arn_123", "amch_123", {
+      outcome: "a",
+      rationale_ref: "note://2",
+    });
+    const [, init] = fetchMock.mock.calls[0];
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://services.test/api/v1/arena/arenas/arn_123/matches/amch_123/juror-votes",
+      expect.objectContaining({ method: "POST" }),
+    );
+    expect(JSON.parse(init.body)).toEqual({
+      outcome: "a",
+      rationale_ref: "note://2",
+    });
+  });
+
+  it("listArenas registered uses the registered query parameter", async () => {
+    const api = makeArenaApi("http://services.test", "k");
+    await api.listArenas({ registered: true });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://services.test/api/v1/arena/arenas?registered=true",
+      expect.objectContaining({ method: "GET" }),
+    );
+  });
+
+  it("getLeaderboard hits the leaderboard route", async () => {
+    const api = makeArenaApi("http://services.test", "k");
+    await api.getLeaderboard("arn_123");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://services.test/api/v1/arena/arenas/arn_123/leaderboard",
+      expect.objectContaining({ method: "GET" }),
+    );
+  });
+
+  it("getCategoryLeaderboard hits the category leaderboard route", async () => {
+    const api = makeArenaApi("http://services.test", "k");
+    await api.getCategoryLeaderboard({ topic: "coding", subtopic: "patches" }, "match");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://services.test/api/v1/arena/leaderboard?category_topic=coding&category_subtopic=patches&mode=match",
+      expect.objectContaining({ method: "GET" }),
+    );
+  });
+
+  it("sends authorization and content-type headers", async () => {
+    const api = makeArenaApi("http://services.test", "k");
+    await api.listOffers();
+    const [, init] = fetchMock.mock.calls[0];
+    expect(init.headers).toMatchObject({
+      Authorization: "Bearer k",
+      "Content-Type": "application/json",
+    });
+  });
+
+  it("turns non-2xx responses into ApiError", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ detail: "arena_not_found" }, { ok: false, status: 404 }));
+    const api = makeArenaApi("http://services.test", "k");
+    await expect(api.getLeaderboard("missing")).rejects.toMatchObject({
+      name: "ApiError",
+      status: 404,
+      detail: "arena_not_found",
+    } satisfies Partial<ApiError>);
+  });
+});