auto-harness-client 0.6.0 → 0.8.0

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

@@ -0,0 +1,83 @@
+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 { conflictDependencies, isDependencyConflict } from "./dependency-conflict.js";
+
+const USAGE = "usage: auto-harness repo rm <repositoryId> [--json]";
+
+/**
+ * `DELETE /repositories/<id>`. A 409 is handled here rather than by the generic `reportError`
+ * pipeline: the whole point of this command is that the refusal explains itself, one concrete
+ * next step per blocking dependency, rather than a `dependencies` array dumped as raw JSON.
+ */
+export async function runRepoRm(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  const [repositoryId] = positionals;
+  if (!repositoryId || positionals.length > 1) throw new CliUsageError(USAGE);
+  const repositorySegment = pathSegment(repositoryId, "repositoryId");
+  const client = await createClient(flags, io);
+  try {
+    await client.request(`/repositories/${repositorySegment}`, {
+      method: "DELETE",
+    });
+  } catch (error) {
+    if (!isDependencyConflict(error)) throw error;
+    return printConflict(io, flags, error, repositoryId);
+  }
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ deleted: true, id: repositoryId }, null, 2)}\n`);
+  } else {
+    io.stdout.write(`repository ${repositoryId} deleted\n`);
+  }
+  return 0;
+}
+
+function printConflict(io, flags, error, repositoryId) {
+  const dependencies = conflictDependencies(error);
+  const hints = dependencies.map((dependency) => hintFor(dependency, dependencies, repositoryId));
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ deleted: false, dependencies, hints }, null, 2)}\n`);
+    return 1;
+  }
+  io.stderr.write(`error: ${error.message} (HTTP ${error.status}, ${error.code})\n`);
+  for (const hint of hints) io.stderr.write(`  ${hint}\n`);
+  return 1;
+}
+
+/** One concrete next step per dependency `kind`. `worktree` is special-cased: worktrees are
+ * removed by detaching the repository from its host, so the hint names that host — taken from a
+ * sibling `host-inventory` dependency in the same response when present, else the literal
+ * placeholder `<hostId>`. */
+function hintFor(dependency, dependencies, repositoryId) {
+  const { kind, id, status } = dependency;
+  if (kind === "schedule") return `${kind} ${id}: auto-harness api DELETE /schedules/${id}`;
+  if (kind === "session") {
+    return (
+      `${kind} ${id} is still running (status: ${status}); wait for it, or ` +
+      `auto-harness api POST /sessions/${id}/cancel`
+    );
+  }
+  if (kind === "session-drain") {
+    return (
+      `${kind} ${id} (status: ${status}): auto-harness api POST ` +
+      `/repositories/${repositoryId}/session-drains/${id}/release`
+    );
+  }
+  if (kind === "host-inventory") {
+    return `${kind} ${id}: auto-harness host repo rm ${id} ${repositoryId}`;
+  }
+  if (kind === "worktree") {
+    const host = dependencies.find((candidate) => candidate.kind === "host-inventory");
+    const hostId = host ? host.id : "<hostId>";
+    return `${kind} ${id}: auto-harness host repo rm ${hostId} ${repositoryId}`;
+  }
+  if (kind === "integration" && id === "github-ingress") {
+    return `${kind} ${id}: remove this repository's binding from the GitHub ingress configuration`;
+  }
+  if (kind === "integration") return `${kind} ${id}: remove or retarget integration ${id}`;
+  return `${kind} ${id}`;
+}

package/src/cli/commands/repo.js

@@ -0,0 +1,18 @@
+import { CliUsageError } from "../cli-errors.js";
+import { runRepoAdd } from "./repo-add.js";
+import { runRepoList } from "./repo-list.js";
+import { runRepoRm } from "./repo-rm.js";
+
+const USAGE = `usage: auto-harness repo <subcommand> ...
+  auto-harness repo add --name <name> --url <url> [--default-branch <branch>] [--json]
+  auto-harness repo list [--limit N] [--cursor C] [--all] [--json]
+  auto-harness repo rm <repositoryId> [--json]`;
+
+/** Dispatches `repo <subcommand>` to its own module — mirrors `host.js`'s own dispatch. */
+export async function runRepo(argv, io) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand === "add") return runRepoAdd(rest, io);
+  if (subcommand === "list") return runRepoList(rest, io);
+  if (subcommand === "rm") return runRepoRm(rest, io);
+  throw new CliUsageError(USAGE);
+}

package/src/cli/commands/service-account-create.js

@@ -0,0 +1,114 @@
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+import { allowlistAccount, formatAccountLine } from "../service-account-format.js";
+
+const USAGE =
+  "usage: auto-harness service-account create --name <name> --role <role> " +
+  "[--bound-host <hostId>] [--repositories <id,id,...>] (--key-file <path> | --print-key) [--json]";
+
+/**
+ * `POST /auth/service-accounts`. The response's `apiKey` is shown exactly once — the server only
+ * stores a hash — so `--key-file`/`--print-key` is a required, mutually-exclusive choice about
+ * where that one-time value goes, validated (along with `--repositories`) before any request.
+ */
+export async function runServiceAccountCreate(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [
+      ...GLOBAL_VALUE_FLAGS,
+      "--name",
+      "--role",
+      "--bound-host",
+      "--repositories",
+      "--key-file",
+    ],
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--print-key", "--json"],
+  });
+  if (positionals.length > 0 || !flags["--name"] || !flags["--role"]) {
+    throw new CliUsageError(USAGE);
+  }
+  // An empty value (`--key-file "$UNSET"`) is a mistake, not an absent flag, and both must be
+  // caught before the request: an empty --key-file creates the account and only then fails to
+  // write its one-time key, orphaning it; an empty --bound-host sends `boundHostId: ""`, which
+  // risks minting an unbound key where a host-bound one was meant.
+  for (const name of ["--key-file", "--bound-host"]) {
+    if (flags[name] !== undefined && flags[name].trim() === "") {
+      throw new CliUsageError(`${name} was given an empty value`);
+    }
+  }
+  const hasKeyFile = flags["--key-file"] !== undefined;
+  const hasPrintKey = Boolean(flags["--print-key"]);
+  if (hasKeyFile === hasPrintKey) {
+    throw new CliUsageError("exactly one of --key-file or --print-key is required");
+  }
+  if (hasPrintKey && flags["--json"]) {
+    throw new CliUsageError("--json and --print-key cannot be combined");
+  }
+  const allowedRepositoryIds = parseRepositories(flags["--repositories"]);
+  if (hasKeyFile) await assertKeyFileAbsent(flags["--key-file"], io);
+  const client = await createClient(flags, io);
+  const result = await client.request("/auth/service-accounts", {
+    method: "POST",
+    body: JSON.stringify(buildBody(flags, allowedRepositoryIds)),
+  });
+  const account = allowlistAccount(result.account);
+  return hasKeyFile
+    ? finishKeyFile(io, flags["--key-file"], flags["--json"], account, result.apiKey)
+    : finishPrintKey(io, account, result.apiKey);
+}
+
+function buildBody(flags, allowedRepositoryIds) {
+  return {
+    name: flags["--name"],
+    role: flags["--role"],
+    ...(flags["--bound-host"] !== undefined ? { boundHostId: flags["--bound-host"] } : {}),
+    ...(allowedRepositoryIds !== undefined ? { allowedRepositoryIds } : {}),
+  };
+}
+
+function parseRepositories(value) {
+  if (value === undefined) return undefined;
+  const ids = value.split(",");
+  if (ids.some((id) => id === "")) {
+    throw new CliUsageError("--repositories must be a comma-separated list with no empty entries");
+  }
+  return ids;
+}
+
+/** Best-effort pre-check so an obviously doomed request never fires; the atomic `wx` write in
+ * `finishKeyFile` is the real guarantee against overwriting an existing file. */
+async function assertKeyFileAbsent(path, io) {
+  let exists = true;
+  try {
+    await io.readFile(path, "utf8");
+  } catch {
+    exists = false;
+  }
+  if (exists)
+    throw new CliUsageError(`--key-file ${path} already exists; refusing to overwrite it`);
+}
+
+async function finishKeyFile(io, path, json, account, apiKey) {
+  try {
+    await io.writeFileExclusive(path, `${apiKey}\n`, { mode: 0o600 });
+  } catch (error) {
+    throw new Error(
+      `service account ${account.id} was created but its key could not be written to ${path} ` +
+        `(${error.message}); the key is now lost — remove it with ` +
+        `\`auto-harness service-account rm ${account.id}\` and create a new one`,
+      { cause: error },
+    );
+  }
+  if (json) {
+    io.stdout.write(`${JSON.stringify(account, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(`service account ${account.id} created\nkey written to ${path}\n`);
+  return 0;
+}
+
+function finishPrintKey(io, account, apiKey) {
+  io.stderr.write(`${formatAccountLine(account)}\n`);
+  io.stdout.write(`${apiKey}\n`);
+  return 0;
+}

package/src/cli/commands/service-account-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";
+import { allowlistAccount, formatAccountLine } from "../service-account-format.js";
+
+// Mirrors `host list`'s and `repo list`'s own cap and guard.
+const MAX_ALL_PAGES = 20;
+
+/**
+ * `GET /auth/service-accounts`, paged with `limit`/`cursor`. Unlike `host list`/`repo list`,
+ * `--json` does *not* print the raw page: items are already server-sanitized, but this allowlists
+ * them anyway as defense in depth (see `service-account-format.js`) — including in JSON, so a
+ * field outside the allowlist can never leak through either output mode.
+ */
+export async function runServiceAccountList(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(
+      `service-account 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 ? `/auth/service-accounts?${suffix}` : "/auth/service-accounts";
+}
+
+async function runListOnePage(client, flags, io) {
+  const page = await client.request(buildQuery(flags, flags["--cursor"]));
+  const items = (page.items ?? []).map(allowlistAccount);
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ items, nextCursor: page.nextCursor }, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(formatAccountLines(items));
+  if (page.nextCursor) {
+    io.stdout.write(
+      `more service accounts 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 ?? []).map(allowlistAccount));
+    cursor = page.nextCursor || undefined;
+    if (!cursor) break;
+    if (seenCursors.has(cursor)) {
+      throw new Error("repeated pagination cursor for /auth/service-accounts");
+    }
+    seenCursors.add(cursor);
+  }
+  if (cursor) {
+    io.stderr.write(
+      `warning: --all stopped after ${MAX_ALL_PAGES} pages; more service accounts remain ` +
+        `(nextCursor: ${cursor})\n`,
+    );
+  }
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ items }, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(formatAccountLines(items));
+  return 0;
+}
+
+function formatAccountLines(items) {
+  if (items.length === 0) return "(no service accounts)\n";
+  return `${items.map(formatAccountLine).join("\n")}\n`;
+}

package/src/cli/commands/service-account-rm.js

@@ -0,0 +1,48 @@
+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 { conflictDependencies, isDependencyConflict } from "./dependency-conflict.js";
+
+const USAGE = "usage: auto-harness service-account rm <id> [--json]";
+
+/** `DELETE /auth/service-accounts/<id>`. A conflict is handled here, generically — one line per
+ * dependency (`kind` + `id`) — rather than by the generic `reportError` pipeline, matching
+ * `repo rm`'s pattern without `repo rm`'s per-kind hints. */
+export async function runServiceAccountRm(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  const [id] = positionals;
+  if (!id || positionals.length > 1) throw new CliUsageError(USAGE);
+  const idSegment = pathSegment(id, "id");
+  const client = await createClient(flags, io);
+  try {
+    await client.request(`/auth/service-accounts/${idSegment}`, {
+      method: "DELETE",
+    });
+  } catch (error) {
+    if (!isDependencyConflict(error)) throw error;
+    return printConflict(io, flags, error, id);
+  }
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ deleted: true, id }, null, 2)}\n`);
+  } else {
+    io.stdout.write(`service account ${id} deleted\n`);
+  }
+  return 0;
+}
+
+function printConflict(io, flags, error, id) {
+  const dependencies = conflictDependencies(error);
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ deleted: false, id, dependencies }, null, 2)}\n`);
+    return 1;
+  }
+  io.stderr.write(`error: ${error.message} (HTTP ${error.status}, ${error.code})\n`);
+  for (const dependency of dependencies) {
+    io.stderr.write(`  ${dependency.kind} ${dependency.id}\n`);
+  }
+  return 1;
+}

package/src/cli/commands/service-account.js

@@ -0,0 +1,19 @@
+import { CliUsageError } from "../cli-errors.js";
+import { runServiceAccountCreate } from "./service-account-create.js";
+import { runServiceAccountList } from "./service-account-list.js";
+import { runServiceAccountRm } from "./service-account-rm.js";
+
+const USAGE = `usage: auto-harness service-account <subcommand> ...
+  auto-harness service-account list [--limit N] [--cursor C] [--all] [--json]
+  auto-harness service-account create --name <name> --role <role> [--bound-host <hostId>]
+    [--repositories <id,id,...>] (--key-file <path> | --print-key) [--json]
+  auto-harness service-account rm <id> [--json]`;
+
+/** Dispatches `service-account <subcommand>` to its own module — mirrors `host.js`'s dispatch. */
+export async function runServiceAccount(argv, io) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand === "list") return runServiceAccountList(rest, io);
+  if (subcommand === "create") return runServiceAccountCreate(rest, io);
+  if (subcommand === "rm") return runServiceAccountRm(rest, io);
+  throw new CliUsageError(USAGE);
+}

package/src/cli/commands/session-cancel.js

@@ -0,0 +1,28 @@
+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 { formatSessionLine } from "../session-format.js";
+
+const USAGE = "usage: auto-harness session cancel <sessionId> [--json]";
+
+/** `POST /sessions/<id>/cancel`, via the library's `cancelSession()` (which encodes the id
+ * itself). A 404 (unknown id) or 409 (already terminal) surfaces through the normal
+ * `reportError` path in `main.js`, same as every other command. */
+export async function runSessionCancel(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  const [sessionId] = positionals;
+  if (!sessionId || positionals.length > 1) throw new CliUsageError(USAGE);
+  // Validates before any request; the encoded value itself is unused since
+  // client.cancelSession() encodes the raw id again on its own.
+  pathSegment(sessionId, "sessionId");
+  const client = await createClient(flags, io);
+  const session = await client.cancelSession(sessionId);
+  io.stdout.write(
+    flags["--json"] ? `${JSON.stringify(session, null, 2)}\n` : formatSessionLine(session),
+  );
+  return 0;
+}

package/src/cli/commands/session-create.js

@@ -0,0 +1,117 @@
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+import { formatSessionLine } from "../session-format.js";
+import { waitForSession } from "../wait-for-session.js";
+import { resolveSessionTarget } from "./session-target.js";
+
+const USAGE =
+  "usage: auto-harness session create --repo <repositoryId> " +
+  "(--provider <id|name> | --command <id|name>) --prompt <text> [--timeout <seconds>] " +
+  "[--ref <ref>] [--concurrency-id <id>] [--wait [--wait-timeout <seconds>]] [--json]";
+
+const VALUE_FLAGS = [
+  "--repo",
+  "--provider",
+  "--command",
+  "--prompt",
+  "--timeout",
+  "--ref",
+  "--concurrency-id",
+  "--wait-timeout",
+];
+
+// Mirrors the create-session form's own default in
+// services/web/src/components/session-timeout-field.tsx (`SessionTimeoutField`,
+// `initialSeconds = 600`). The server requires `timeout`; there is no server-side default
+// (`sessionTimeoutError` in modules/shared/src/validation.ts rejects `undefined`).
+const DEFAULT_TIMEOUT_SECONDS = 600;
+
+// Arbitrary, small: keeps `--wait` responsive without hammering the API.
+const WAIT_POLL_INTERVAL_MS = 2_000;
+
+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 validateFlags(flags) {
+  for (const name of VALUE_FLAGS) {
+    if (flags[name] !== undefined && flags[name].trim() === "") {
+      throw new CliUsageError(`${name} was given an empty value`);
+    }
+  }
+  if (!flags["--repo"] || flags["--prompt"] === undefined) throw new CliUsageError(USAGE);
+  const hasProvider = flags["--provider"] !== undefined;
+  const hasCommand = flags["--command"] !== undefined;
+  if (hasProvider === hasCommand) {
+    throw new CliUsageError("exactly one of --provider or --command is required");
+  }
+  if (flags["--wait-timeout"] !== undefined && !flags["--wait"]) {
+    throw new CliUsageError("--wait-timeout requires --wait");
+  }
+}
+
+/**
+ * `POST /sessions`. `--provider`/`--command` accept either an id or a name (see
+ * `session-target.js`); `--timeout` defaults to `DEFAULT_TIMEOUT_SECONDS` since the server
+ * requires it but has no default of its own. With `--wait`, polls via `waitForSession()` —
+ * status changes go to stderr, the final session record to stdout — and exits 0 only when the
+ * session `completed` with `exitCode === 0`; any other terminal status, or the wait timing out,
+ * exits 1 (a timed-out wait never cancels the session).
+ */
+export async function runSessionCreate(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, ...VALUE_FLAGS],
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--wait", "--json"],
+  });
+  if (positionals.length > 0) throw new CliUsageError(USAGE);
+  validateFlags(flags);
+  const timeout =
+    flags["--timeout"] !== undefined
+      ? parsePositiveNumber(flags["--timeout"], "--timeout")
+      : DEFAULT_TIMEOUT_SECONDS;
+  const waitTimeoutSeconds = flags["--wait"]
+    ? flags["--wait-timeout"] !== undefined
+      ? parsePositiveNumber(flags["--wait-timeout"], "--wait-timeout")
+      : timeout
+    : undefined;
+
+  const client = await createClient(flags, io);
+  const target = await resolveSessionTarget(client, flags);
+  const created = await client.createSession({
+    repositoryId: flags["--repo"],
+    prompt: flags["--prompt"],
+    target,
+    timeout,
+    ...(flags["--ref"] !== undefined ? { ref: flags["--ref"] } : {}),
+    ...(flags["--concurrency-id"] !== undefined
+      ? { concurrencyId: flags["--concurrency-id"] }
+      : {}),
+  });
+  if (!flags["--wait"]) return writeResult(io, flags, created, 0);
+
+  const { timedOut, session } = await waitForSession(client, created.id, {
+    timeoutMs: waitTimeoutSeconds * 1000,
+    intervalMs: WAIT_POLL_INTERVAL_MS,
+    onStatus: (status) => io.stderr.write(`session ${created.id}: ${status}\n`),
+  });
+  if (timedOut) {
+    io.stderr.write(
+      `session ${created.id} is still running after ${waitTimeoutSeconds}s; not cancelling it\n`,
+    );
+    return writeResult(io, flags, session, 1);
+  }
+  const succeeded = session.status === "completed" && session.exitCode === 0;
+  return writeResult(io, flags, session, succeeded ? 0 : 1);
+}
+
+function writeResult(io, flags, session, exitCode) {
+  io.stdout.write(
+    flags["--json"] ? `${JSON.stringify(session, null, 2)}\n` : formatSessionLine(session),
+  );
+  return exitCode;
+}

package/src/cli/commands/session-get.js

@@ -0,0 +1,26 @@
+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 { formatSessionLine } from "../session-format.js";
+
+const USAGE = "usage: auto-harness session get <sessionId> [--json]";
+
+/** `GET /sessions/<id>`, via the library's `getSession()` (which encodes the id itself). */
+export async function runSessionGet(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  const [sessionId] = positionals;
+  if (!sessionId || positionals.length > 1) throw new CliUsageError(USAGE);
+  // Validates before any request (and before an admin-mode login); the encoded value itself is
+  // unused since client.getSession() encodes the raw id again on its own.
+  pathSegment(sessionId, "sessionId");
+  const client = await createClient(flags, io);
+  const session = await client.getSession(sessionId);
+  io.stdout.write(
+    flags["--json"] ? `${JSON.stringify(session, null, 2)}\n` : formatSessionLine(session),
+  );
+  return 0;
+}

package/src/cli/commands/session-logs.js

@@ -0,0 +1,65 @@
+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";
+
+const USAGE = "usage: auto-harness session logs <sessionId> [--limit N] [--cursor C] [--json]";
+
+// Mirrors DEFAULT_LOG_QUERY_LIMIT in services/api/src/log-query.ts — used only to guess whether
+// a page came back full when --limit was not given (see the pagination note below).
+const DEFAULT_LOG_LIMIT = 1000;
+
+/**
+ * `GET /sessions/<id>/logs`. Unlike `repo list`/`host list`, this endpoint returns `{ items }`
+ * with no `nextCursor` — its only continuation knob is `since` (services/api/src/log-query.ts),
+ * a whole ISO-8601 timestamp, exclusive. This CLI exposes that as `--cursor` for a pagination
+ * vocabulary consistent with the other list commands, mapped straight to `since`. Passing the
+ * last printed item's own `timestamp` back as the next `--cursor` therefore excludes *every*
+ * record sharing that exact timestamp, not only the one already shown — coarser than a true row
+ * cursor, but that is the bounded contract `parseLogQuery` actually offers (the true `after`
+ * cursor is internal-only, used by viewer reconnects, and never exposed over REST). One page is
+ * printed; never looped, per this repo's list/history invariant.
+ */
+export async function runSessionLogs(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--limit", "--cursor"],
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  const [sessionId] = positionals;
+  if (!sessionId || positionals.length > 1) throw new CliUsageError(USAGE);
+  for (const name of ["--limit", "--cursor"]) {
+    if (flags[name] !== undefined && flags[name].trim() === "") {
+      throw new CliUsageError(`${name} was given an empty value`);
+    }
+  }
+  const limit = flags["--limit"] !== undefined ? Number(flags["--limit"]) : DEFAULT_LOG_LIMIT;
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw new CliUsageError("--limit must be a positive integer");
+  }
+  const sessionSegment = pathSegment(sessionId, "sessionId");
+  const client = await createClient(flags, io);
+  const query = new URLSearchParams();
+  if (flags["--limit"] !== undefined) query.set("limit", flags["--limit"]);
+  if (flags["--cursor"] !== undefined) query.set("since", flags["--cursor"]);
+  const suffix = query.toString();
+  const page = await client.request(
+    `/sessions/${sessionSegment}/logs${suffix ? `?${suffix}` : ""}`,
+  );
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify(page, null, 2)}\n`);
+    return 0;
+  }
+  const items = page.items ?? [];
+  io.stdout.write(formatLogLines(items));
+  if (items.length === limit) {
+    io.stdout.write(
+      `more logs may be available; pass --cursor ${items.at(-1).timestamp} to continue\n`,
+    );
+  }
+  return 0;
+}
+
+function formatLogLines(items) {
+  if (items.length === 0) return "(no logs)\n";
+  return `${items.map((item) => `${item.timestamp}  [${item.stream}]  ${item.content}`).join("\n")}\n`;
+}

package/src/cli/commands/session-target.js

@@ -0,0 +1,29 @@
+/**
+ * Resolves `--provider <id|name>` or `--command <id|name>` to a `TargetRef` for `createSession()`.
+ * Exactly one of `flags["--provider"]`/`flags["--command"]` must already be set — callers
+ * validate that mutual-exclusivity/required check before calling this.
+ *
+ * Lists the relevant catalog once (`client.listProviders()`/`listCommands()`) and checks for an
+ * exact `id` match locally. A hit returns an already-id-shaped ref, which `resolveTargetSpecs`
+ * (inside `client.createSession()`) passes straight through with no further request. A miss
+ * returns a `providerName`/`commandName` ref instead — deliberately *not* resolved here — so
+ * `createSession()`'s own `resolveCreateSessionTargets()` resolves it, reusing its exact
+ * not-found/ambiguous-name errors (`UNKNOWN_PROVIDER_NAME`, `AMBIGUOUS_PROVIDER_NAME`, ...)
+ * rather than reimplementing that matching. One consequence: a mistyped id surfaces as
+ * `no provider named "<value>"`, not a distinct "unknown id" error.
+ */
+export async function resolveSessionTarget(client, flags) {
+  if (flags["--provider"] !== undefined) {
+    return resolveOne(
+      await client.listProviders(),
+      flags["--provider"],
+      "providerId",
+      "providerName",
+    );
+  }
+  return resolveOne(await client.listCommands(), flags["--command"], "commandId", "commandName");
+}
+
+function resolveOne(items, value, idKey, nameKey) {
+  return items.some((item) => item.id === value) ? { [idKey]: value } : { [nameKey]: value };
+}

package/src/cli/commands/session.js

@@ -0,0 +1,22 @@
+import { CliUsageError } from "../cli-errors.js";
+import { runSessionCancel } from "./session-cancel.js";
+import { runSessionCreate } from "./session-create.js";
+import { runSessionGet } from "./session-get.js";
+import { runSessionLogs } from "./session-logs.js";
+
+const USAGE = `usage: auto-harness session <subcommand> ...
+  auto-harness session create --repo <repositoryId> (--provider <id|name> | --command <id|name>) --prompt <text>
+    [--timeout <seconds>] [--ref <ref>] [--concurrency-id <id>] [--wait [--wait-timeout <seconds>]] [--json]
+  auto-harness session get <sessionId> [--json]
+  auto-harness session logs <sessionId> [--limit N] [--cursor C] [--json]
+  auto-harness session cancel <sessionId> [--json]`;
+
+/** Dispatches `session <subcommand>` to its own module — mirrors `host.js`'s own dispatch. */
+export async function runSession(argv, io) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand === "create") return runSessionCreate(rest, io);
+  if (subcommand === "get") return runSessionGet(rest, io);
+  if (subcommand === "logs") return runSessionLogs(rest, io);
+  if (subcommand === "cancel") return runSessionCancel(rest, io);
+  throw new CliUsageError(USAGE);
+}