auto-harness-client 0.6.0 → 0.8.0

package/src/cli/commands/host-smoke-session-attempt.js

@@ -0,0 +1,104 @@
+import { step } from "./host-smoke-format.js";
+import { waitForSmokeSession } from "./host-smoke-poll.js";
+
+// A host's cached inventory only refreshes on its own periodic poll (there is no
+// push-on-write) — see host-smoke-provider.js's doc comment for the full explanation. Five
+// attempts of doubling backoff (2s, 4s, 8s, 16s, capped at 16s) covers the daemon's own
+// default 15s poll at least once while staying well inside a generous --timeout.
+const SETUP_FAILURE_RETRY_LIMIT = 5;
+const SETUP_FAILURE_RETRY_BASE_MS = 2_000;
+const SETUP_FAILURE_RETRY_MAX_MS = 16_000;
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** True for the one specific `setup_failed` shape thrown by
+ * `services/host-daemon/src/worktree-manager.ts` when a host's own cached inventory hasn't
+ * caught up with a just-attached repository yet. */
+function isUnknownRepositorySetupFailure(session) {
+  return (
+    session.status === "failed" &&
+    session.errorCode === "setup_failed" &&
+    typeof session.errorMessage === "string" &&
+    session.errorMessage.startsWith("Unknown repository:")
+  );
+}
+
+/**
+ * Creates a session and waits for it, retrying up to `SETUP_FAILURE_RETRY_LIMIT` times — with
+ * exponential backoff, bounded by the same overall `timeoutSeconds` deadline as everything
+ * else — but only for that one exact, unambiguous failure signature. Every other terminal shape
+ * (a real setup/session failure, `usage_limit`, a genuine timeout, a `createSession` rejection)
+ * returns immediately, unretried. A `waitForSmokeSession` rejection (a genuine `getSession`
+ * failure — network error, 5xx — not a `UsageLimitSignal`, which it already converts) is caught
+ * here too: it is not one of the narrow shapes above, and letting it propagate would abort every
+ * remaining `--provider` in `host-smoke.js`'s loop and get misreported as a top-level
+ * `setupError`. The created session's id is deliberately left in `activeSessionIds` (never
+ * removed on this path) so `teardownSmoke`'s own safety net cancels it. Resolves to
+ * `{ kind: "create_failed", message }`, `{ kind: "session_wait_failed", sessionId, message }`, or
+ * `{ kind, session, sessionId }` where `kind` is `waitForSmokeSession`'s own
+ * `"usage_limit" | "timeout" | "terminal"`.
+ */
+export async function runSessionAttempts({
+  client,
+  io,
+  repositoryId,
+  providerRef,
+  target,
+  marker,
+  timeoutSeconds,
+  activeSessionIds,
+  sleep = defaultSleep,
+  now = Date.now,
+  intervalMs,
+}) {
+  const deadline = now() + timeoutSeconds * 1000;
+  for (let attempt = 1; attempt <= SETUP_FAILURE_RETRY_LIMIT; attempt += 1) {
+    let created;
+    try {
+      created = await client.createSession({
+        repositoryId,
+        prompt: `Reply with exactly: ${marker}`,
+        target,
+        timeout: timeoutSeconds,
+      });
+    } catch (error) {
+      return { kind: "create_failed", message: error.message };
+    }
+    activeSessionIds.add(created.id);
+    step(io, true, `provider ${providerRef}: created session ${created.id}`);
+
+    let outcome;
+    try {
+      outcome = await waitForSmokeSession(client, created.id, {
+        timeoutMs: Math.max(1, deadline - now()),
+        intervalMs,
+        sleep,
+        now,
+        onStatus: (status) => io.stderr.write(`  session ${created.id}: ${status}\n`),
+      });
+    } catch (error) {
+      return { kind: "session_wait_failed", sessionId: created.id, message: error.message };
+    }
+    if (outcome.kind === "terminal") activeSessionIds.delete(created.id);
+
+    const retryable =
+      outcome.kind === "terminal" && isUnknownRepositorySetupFailure(outcome.session);
+    const budgetMs = deadline - now();
+    if (!retryable || attempt === SETUP_FAILURE_RETRY_LIMIT || budgetMs <= 0) {
+      return { ...outcome, sessionId: created.id };
+    }
+    io.stderr.write(
+      `  provider ${providerRef}: host has not picked up the newly attached repository yet ` +
+        `(attempt ${attempt}/${SETUP_FAILURE_RETRY_LIMIT}); retrying\n`,
+    );
+    const backoffMs = Math.min(
+      SETUP_FAILURE_RETRY_BASE_MS * 2 ** (attempt - 1),
+      SETUP_FAILURE_RETRY_MAX_MS,
+    );
+    await sleep(Math.min(backoffMs, budgetMs));
+  }
+  /* v8 ignore next 2 -- the loop above always returns before falling out */
+  return { kind: "create_failed", message: "unreachable" };
+}

package/src/cli/commands/host-smoke-teardown.js

@@ -0,0 +1,164 @@
+import { AutoHarnessError } from "../../index.js";
+import { pathSegment } from "../path-segment.js";
+import { isDependencyConflict } from "./dependency-conflict.js";
+import { detachRepository } from "./detach-repository.js";
+import { step } from "./host-smoke-format.js";
+
+// A dependency 409 here almost always means the worktree/host-inventory projection the delete
+// guard reads (see services/api/src/control-plane-delete-guards.ts) hasn't caught up with the
+// detach write this same teardown just made, or a just-cancelled session is still winding down
+// — a few short retries clear both without a long wait. The same budget also covers a delete
+// request that itself fails transiently (5xx, or a network/timeout error below the HTTP layer) —
+// see `isTransientDeleteFailure` below.
+const DELETE_ATTEMPTS = 5;
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Cancels every session still tracked as active — a per-provider timeout/usage-limit already
+ * cancels its own session and untracks it (see `host-smoke-provider.js`); what is left here is
+ * only the safety net for a session whose fate an unexpected exception left unresolved. Never
+ * throws: a cancel failure is reported as a step, the id is kept (not deleted) in
+ * `activeSessionIds`, and it comes back in `uncancelled` for the caller to report — a 409 means
+ * the session raced to terminal on its own, which is fine to drop. */
+async function cancelOutstanding(client, io, activeSessionIds) {
+  const cancelled = [];
+  const uncancelled = [];
+  // Safe to delete the current entry mid-iteration (a Set only skips an entry deleted before
+  // it is reached); nothing is added to the set during this loop.
+  for (const sessionId of activeSessionIds) {
+    try {
+      await client.cancelSession(sessionId);
+      cancelled.push(sessionId);
+      activeSessionIds.delete(sessionId);
+      step(io, true, `teardown: cancelled session ${sessionId}`);
+    } catch (error) {
+      if (error instanceof AutoHarnessError && error.status === 409) {
+        cancelled.push(sessionId);
+        activeSessionIds.delete(sessionId);
+        step(io, true, `teardown: session ${sessionId} was already terminal`);
+      } else {
+        uncancelled.push(sessionId);
+        step(io, false, `teardown: cancel session ${sessionId} failed: ${error.message}`);
+      }
+    }
+  }
+  return { cancelled, uncancelled };
+}
+
+/** True for a delete failure worth retrying beyond the existing dependency-409 case: an HTTP 5xx
+ * (server-side, likely transient) or a rejection that never reached the HTTP layer at all (a
+ * network error, or `AutoHarnessRequestTimeoutError`) — neither is `AutoHarnessError`'s own 4xx
+ * shape, so both are retried like a 5xx. A 409 is intentionally *not* one of these: it is the
+ * server definitively refusing (still has live dependents), not evidence the request itself may
+ * have landed. */
+function isTransientDeleteFailure(error) {
+  return !(error instanceof AutoHarnessError) || error.status >= 500;
+}
+
+/** `DELETE /repositories/<id>`, retrying a dependency 409 or a transient failure
+ * (`isTransientDeleteFailure`) a few times with a short backoff (`sleep` injected so tests never
+ * really wait). Once a transient failure has actually happened, a later 404 is treated as success
+ * — the delete most likely landed and the connection dropped before the response did — rather
+ * than as a genuine "nothing to delete" failure, which a 404 with no prior transient failure
+ * still is. Any other error, or the last attempt, is returned rather than thrown — teardown must
+ * never throw (see its own doc comment). */
+async function deleteRepositoryWithRetry(client, repositoryId, sleep) {
+  let sawTransientFailure = false;
+  for (let attempt = 1; attempt <= DELETE_ATTEMPTS; attempt += 1) {
+    try {
+      await client.request(`/repositories/${pathSegment(repositoryId, "repositoryId")}`, {
+        method: "DELETE",
+      });
+      return { ok: true };
+    } catch (error) {
+      const notFound = error instanceof AutoHarnessError && error.status === 404;
+      if (sawTransientFailure && notFound) return { ok: true };
+      const transient = isTransientDeleteFailure(error);
+      if ((!transient && !isDependencyConflict(error)) || attempt === DELETE_ATTEMPTS) {
+        return { ok: false, error };
+      }
+      if (transient) sawTransientFailure = true;
+      await sleep(Math.min(250 * attempt, 2_000));
+    }
+  }
+  /* v8 ignore next 2 -- the loop above always returns before falling out */
+  return { ok: false, error: new Error("unreachable") };
+}
+
+/**
+ * Runs from the caller's `finally`, no matter which earlier step failed or threw. Cancels any
+ * session smoke created that never reached a terminal status on its own, detaches the
+ * repository only if it was actually attached (an attach that itself threw never wrote
+ * anything), then deletes the repository, retrying a dependency 409 or a transient failure a few
+ * times. Never throws — a teardown failure is reported through its own `ok: false` result plus a
+ * cleanup hint on stderr, so it always composes safely inside a `finally` (an exception thrown
+ * from a `finally` would replace whatever error the `try` was already failing with). `ok` is
+ * false whenever the repository is left behind (a failed detach or delete) **or** any session
+ * failed to cancel — a still-live session blocks the delete guard, so an uncancelled session and
+ * a leftover repository often go together, but each is reported (and each gets its own cleanup
+ * command) independently of the other.
+ */
+export async function teardownSmoke({
+  client,
+  io,
+  hostId,
+  repositoryId,
+  attached,
+  activeSessionIds,
+  sleep = defaultSleep,
+}) {
+  const { cancelled: cancelledSessionIds, uncancelled: uncancelledSessionIds } =
+    await cancelOutstanding(client, io, activeSessionIds);
+
+  let detached = false;
+  let detachError;
+  if (attached) {
+    try {
+      await detachRepository(client, hostId, repositoryId);
+      detached = true;
+      step(io, true, `teardown: detached repository ${repositoryId} from host ${hostId}`);
+    } catch (error) {
+      detachError = error;
+      step(io, false, `teardown: detach repository ${repositoryId} failed: ${error.message}`);
+    }
+  }
+
+  const deleteResult = await deleteRepositoryWithRetry(client, repositoryId, sleep);
+  if (deleteResult.ok) {
+    step(io, true, `teardown: deleted repository ${repositoryId}`);
+  } else {
+    step(
+      io,
+      false,
+      `teardown: delete repository ${repositoryId} failed: ${deleteResult.error.message}`,
+    );
+  }
+
+  const repositoryLeftover = Boolean(detachError) || !deleteResult.ok;
+  const ok = !repositoryLeftover && uncancelledSessionIds.length === 0;
+  if (!ok) {
+    for (const sessionId of uncancelledSessionIds) {
+      io.stderr.write(
+        `leftover session ${sessionId} — finish cleanup with:\n` +
+          `  auto-harness session cancel ${sessionId}\n`,
+      );
+    }
+    if (repositoryLeftover) {
+      io.stderr.write(
+        `leftover repository ${repositoryId} — finish cleanup with:\n` +
+          `  auto-harness host repo rm ${hostId} ${repositoryId}\n` +
+          `  auto-harness repo rm ${repositoryId}\n`,
+      );
+    }
+  }
+  return {
+    ok,
+    cancelledSessionIds,
+    uncancelledSessionIds,
+    detached,
+    repositoryDeleted: deleteResult.ok,
+    ...(repositoryLeftover ? { leftoverRepositoryId: repositoryId } : {}),
+  };
+}

package/src/cli/commands/host-smoke.js

@@ -0,0 +1,151 @@
+import { randomBytes } from "node:crypto";
+
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+import { pathSegment } from "../path-segment.js";
+import { attachRepository } from "./attach-repository.js";
+import { printSummary, step } from "./host-smoke-format.js";
+import { runProviderSmoke } from "./host-smoke-provider.js";
+import { createSmokeRepository, smokeInventoryEntry } from "./host-smoke-repository.js";
+import { teardownSmoke } from "./host-smoke-teardown.js";
+
+const USAGE =
+  "usage: auto-harness host smoke <hostId> --repo-path <path> --provider <id|name> " +
+  "[--provider <id|name>]... [--timeout <seconds>] [--json]";
+
+// Copied from MAX_SESSION_TIMEOUT_SECONDS in modules/shared/src/validation.ts (7 days) — this
+// package is dependency-free (no @auto-harness/shared import), so the value is duplicated here
+// rather than imported. Keep in sync if the shared limit ever changes.
+const MAX_SESSION_TIMEOUT_SECONDS = 7 * 24 * 60 * 60;
+
+// A real provider turn is a full model round trip through a real host, not the quick one-shot
+// prompt `session create`'s own 600s default assumes — generous, but still well inside the
+// server's own ceiling above.
+const DEFAULT_TIMEOUT_SECONDS = 300;
+
+// Arbitrary, small: keeps the wait responsive without hammering the API (matches session
+// create --wait's own poll interval).
+const WAIT_POLL_INTERVAL_MS = 2_000;
+
+function defaultRandomHex(bytes) {
+  return randomBytes(bytes).toString("hex");
+}
+
+function parsePositiveNumber(value, label) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new CliUsageError(`${label} must be a positive number`);
+  }
+  return parsed;
+}
+
+function parseArgs(argv) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--repo-path", "--timeout"],
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+    repeatableFlags: ["--provider"],
+  });
+  const [hostId] = positionals;
+  const providers = flags["--provider"] ?? [];
+  if (!hostId || positionals.length > 1 || !flags["--repo-path"] || providers.length === 0) {
+    throw new CliUsageError(USAGE);
+  }
+  const timeoutSeconds =
+    flags["--timeout"] !== undefined
+      ? parsePositiveNumber(flags["--timeout"], "--timeout")
+      : DEFAULT_TIMEOUT_SECONDS;
+  if (timeoutSeconds > MAX_SESSION_TIMEOUT_SECONDS) {
+    throw new CliUsageError(`--timeout must be at most ${MAX_SESSION_TIMEOUT_SECONDS} seconds`);
+  }
+  return { flags, hostId, providers, repoPath: flags["--repo-path"], timeoutSeconds };
+}
+
+/**
+ * `host smoke <hostId> --repo-path <path> --provider <id|name>... [--timeout <seconds>]
+ * [--json]` — proves a host can run a real provider-routed session end to end, then cleans up
+ * after itself. See `modules/client/README.md` for the full step-by-step contract and the
+ * preconditions on `--repo-path` this command cannot verify itself (it is a HOST path; the CLI
+ * may run elsewhere).
+ *
+ * Every step logs `ok`/`FAIL` to stderr as it happens; stdout stays a clean final summary (or,
+ * with `--json`, the full structured result). Teardown (`teardownSmoke`) always runs, in
+ * `finally`, however far setup or the provider loop got. Exit 0 only when every provider passed
+ * *and* teardown itself succeeded; 1 otherwise (a malformed invocation is the normal `CliUsageError`
+ * path, exit 2, handled by `main.js` before this function is even called for that failure mode).
+ */
+export async function runHostSmoke(argv, io) {
+  const { flags, hostId, providers, repoPath, timeoutSeconds } = parseArgs(argv);
+  pathSegment(hostId, "hostId"); // validate before createClient, which may log in
+  const client = await createClient(flags, io);
+  const randomHex = io.randomHex ?? defaultRandomHex;
+  const sleep = io.sleep;
+  const now = io.now;
+
+  const activeSessionIds = new Set();
+  let repository;
+  let attached = false;
+  let setupError;
+  let teardownResult;
+  const providerResults = [];
+
+  try {
+    repository = await createSmokeRepository(client, randomHex);
+    step(io, true, `created repository ${repository.id} (${repository.name})`);
+
+    const entry = smokeInventoryEntry(repository, repoPath);
+    await attachRepository(client, hostId, entry);
+    attached = true;
+    step(io, true, `attached repository ${repository.id} to host ${hostId} at ${repoPath}`);
+
+    const marker = `AH_SMOKE_${randomHex(8).toUpperCase()}`;
+    for (const providerRef of providers) {
+      const outcome = await runProviderSmoke({
+        client,
+        io,
+        repositoryId: repository.id,
+        providerRef,
+        marker,
+        timeoutSeconds,
+        activeSessionIds,
+        sleep,
+        now,
+        intervalMs: WAIT_POLL_INTERVAL_MS,
+      });
+      providerResults.push(outcome);
+    }
+  } catch (error) {
+    setupError = error;
+    step(io, false, `setup: ${error.message}`);
+  } finally {
+    teardownResult = repository
+      ? await teardownSmoke({
+          client,
+          io,
+          hostId,
+          repositoryId: repository.id,
+          attached,
+          activeSessionIds,
+          sleep,
+        })
+      : {
+          ok: true,
+          cancelledSessionIds: [],
+          uncancelledSessionIds: [],
+          detached: false,
+          repositoryDeleted: false,
+        };
+  }
+
+  const ok = !setupError && providerResults.every((provider) => provider.pass) && teardownResult.ok;
+  const result = {
+    hostId,
+    repositoryId: repository?.id,
+    providers: providerResults,
+    teardown: teardownResult,
+    ok,
+    ...(setupError ? { setupError: setupError.message } : {}),
+  };
+  printSummary(io, flags, result);
+  return ok ? 0 : 1;
+}

package/src/cli/commands/host.js

@@ -0,0 +1,31 @@
+import { CliUsageError } from "../cli-errors.js";
+import { runHostDrain } from "./host-drain.js";
+import { runHostInventory } from "./host-inventory.js";
+import { runHostList } from "./host-list.js";
+import { runHostRepo } from "./host-repo.js";
+import { runHostResume } from "./host-resume.js";
+import { runHostSmoke } from "./host-smoke.js";
+
+const USAGE = `usage: auto-harness host <subcommand> ...
+  auto-harness host list [--online | --offline] [--limit N] [--cursor C] [--all] [--json]
+  auto-harness host drain <hostId> [--json]
+  auto-harness host resume <hostId> [--json]
+  auto-harness host inventory get <hostId> [--json]
+  auto-harness host inventory set <hostId> --file <path|->
+  auto-harness host repo add <hostId> <repositoryId> --path <path> [--worktree <id>=<path>]...
+    [--default-branch <branch>] [--dry-run] [--json]
+  auto-harness host repo rm <hostId> <repositoryId> [--dry-run] [--json]
+  auto-harness host smoke <hostId> --repo-path <path> --provider <id|name>
+    [--provider <id|name>]... [--timeout <seconds>] [--json]`;
+
+/** Dispatches `host <subcommand>` to its own module — mirrors `main.js`'s own dispatch. */
+export async function runHost(argv, io) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand === "list") return runHostList(rest, io);
+  if (subcommand === "drain") return runHostDrain(rest, io);
+  if (subcommand === "resume") return runHostResume(rest, io);
+  if (subcommand === "inventory") return runHostInventory(rest, io);
+  if (subcommand === "repo") return runHostRepo(rest, io);
+  if (subcommand === "smoke") return runHostSmoke(rest, io);
+  throw new CliUsageError(USAGE);
+}

package/src/cli/commands/parse-worktree-flag.js

@@ -0,0 +1,30 @@
+import { CliUsageError } from "../cli-errors.js";
+
+/**
+ * Parses repeated `--worktree <id>=<path>` values (as collected by `parseFlags`'s
+ * `repeatableFlags`) into inventory worktree entries: `{ id, name: id, path, labels: [] }`.
+ * `name` mirrors `id` — the server's own slug check on `name` (see
+ * `modules/shared/src/host-inventory-parse.ts`) is what actually constrains its shape, so this
+ * does not re-validate it. Splits on the *first* `=` so a path containing `=` still parses
+ * correctly; an entry with no `=`, an empty id, or an empty path is a usage error (exit 2), as
+ * is a repeated id — the server would also reject a duplicate worktree id, but only after a
+ * round trip, so catching it here is a strictly better error.
+ */
+export function parseWorktreeFlags(rawValues) {
+  const worktrees = [];
+  const seenIds = new Set();
+  for (const raw of rawValues) {
+    const equals = raw.indexOf("=");
+    if (equals <= 0 || equals === raw.length - 1) {
+      throw new CliUsageError(`--worktree must be <id>=<path>, got: ${raw}`);
+    }
+    const id = raw.slice(0, equals);
+    const path = raw.slice(equals + 1);
+    if (seenIds.has(id)) {
+      throw new CliUsageError(`--worktree id given more than once: ${id}`);
+    }
+    seenIds.add(id);
+    worktrees.push({ id, name: id, path, labels: [] });
+  }
+  return worktrees;
+}

package/src/cli/commands/repo-add.js

@@ -0,0 +1,38 @@
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+
+const USAGE =
+  "usage: auto-harness repo add --name <name> --url <url> [--default-branch <branch>] [--json]";
+
+/**
+ * `POST /repositories`. The response is the created repository record itself — no `{ repository
+ * }` wrapper, matching `GET /repositories/<id>` — so `--json` prints it verbatim. Human output
+ * is one line (id, name), mirroring `repo list`'s per-line format.
+ */
+export async function runRepoAdd(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--name", "--url", "--default-branch"],
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  if (positionals.length > 0 || !flags["--name"] || !flags["--url"]) {
+    throw new CliUsageError(USAGE);
+  }
+  const client = await createClient(flags, io);
+  const repository = await client.request("/repositories", {
+    method: "POST",
+    body: JSON.stringify({
+      name: flags["--name"],
+      url: flags["--url"],
+      ...(flags["--default-branch"] !== undefined
+        ? { defaultBranch: flags["--default-branch"] }
+        : {}),
+    }),
+  });
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify(repository, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(`${repository.id}  ${repository.name}\n`);
+  return 0;
+}

package/src/cli/commands/repo-list.js

@@ -0,0 +1,84 @@
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+
+// This repo's list/history invariant forbids unbounded collection of pages at storage, so
+// `--all` stops here and warns rather than following `nextCursor` forever. Mirrors `host list`.
+const MAX_ALL_PAGES = 20;
+
+/** `GET /repositories`, paged with `limit`/`cursor`. `--all` follows `nextCursor` itself,
+ * capped at `MAX_ALL_PAGES` pages. */
+export async function runRepoList(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--limit", "--cursor"],
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--all", "--json"],
+  });
+  if (positionals.length > 0) {
+    throw new CliUsageError(`repo list takes no arguments; received: ${positionals.join(" ")}`);
+  }
+  const client = await createClient(flags, io);
+  return flags["--all"] ? runListAll(client, flags, io) : runListOnePage(client, flags, io);
+}
+
+function buildQuery(flags, cursor) {
+  const query = new URLSearchParams();
+  if (flags["--limit"] !== undefined) query.set("limit", flags["--limit"]);
+  if (cursor !== undefined) query.set("cursor", cursor);
+  const suffix = query.toString();
+  return suffix ? `/repositories?${suffix}` : "/repositories";
+}
+
+async function runListOnePage(client, flags, io) {
+  const page = await client.request(buildQuery(flags, flags["--cursor"]));
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify(page, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(formatRepoLines(page.items ?? []));
+  if (page.nextCursor) {
+    io.stdout.write(
+      `more repositories available; pass --cursor ${page.nextCursor} to continue (or --all)\n`,
+    );
+  }
+  return 0;
+}
+
+async function runListAll(client, flags, io) {
+  const items = [];
+  const seenCursors = new Set();
+  let cursor = flags["--cursor"];
+  for (let pageCount = 0; pageCount < MAX_ALL_PAGES; pageCount += 1) {
+    const page = await client.request(buildQuery(flags, cursor));
+    items.push(...(page.items ?? []));
+    cursor = page.nextCursor || undefined;
+    if (!cursor) break;
+    // Mirrors the same guard in AutoHarnessClient#listCatalog: a server repeating a cursor is a
+    // bug worth failing loudly on, not something to paper over as "more pages than the cap".
+    if (seenCursors.has(cursor)) throw new Error("repeated pagination cursor for /repositories");
+    seenCursors.add(cursor);
+  }
+  if (cursor) {
+    io.stderr.write(
+      `warning: --all stopped after ${MAX_ALL_PAGES} pages; more repositories remain ` +
+        `(nextCursor: ${cursor})\n`,
+    );
+  }
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ items }, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(formatRepoLines(items));
+  return 0;
+}
+
+function formatRepoLines(items) {
+  if (items.length === 0) return "(no repositories)\n";
+  return `${items.map(formatRepoLine).join("\n")}\n`;
+}
+
+function formatRepoLine(repo) {
+  const parts = [repo.id, repo.name];
+  if (repo.status) parts.push(repo.status);
+  if (repo.url) parts.push(repo.url);
+  return parts.join("  ");
+}