auto-harness-client 0.7.0 → 0.8.0

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

@@ -4,6 +4,7 @@ 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]
@@ -11,7 +12,11 @@ const USAGE = `usage: auto-harness host <subcommand> ...
   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 rm <hostId> <repositoryId> [--dry-run] [--json]`;
+  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) {
@@ -21,5 +26,6 @@ export async function runHost(argv, 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.js

@@ -1,14 +1,17 @@
 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/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);
+}

package/src/cli/main.js

@@ -3,6 +3,7 @@ import { runDoctor } from "./commands/doctor.js";
 import { runHost } from "./commands/host.js";
 import { runRepo } from "./commands/repo.js";
 import { runServiceAccount } from "./commands/service-account.js";
+import { runSession } from "./commands/session.js";
 import { runWhoami } from "./commands/whoami.js";
 import { GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "./config.js";
 import { reportError } from "./report-error.js";
@@ -61,6 +62,7 @@ export async function main(argv, io) {
     if (command === "host") return await runHost(rest, io);
     if (command === "repo") return await runRepo(rest, io);
     if (command === "service-account") return await runServiceAccount(rest, io);
+    if (command === "session") return await runSession(rest, io);
     io.stderr.write(usage());
     return 2;
   } catch (error) {

package/src/cli/session-format.js

@@ -0,0 +1,15 @@
+/**
+ * One-line human summary shared by `session create --wait`, `session get`, and `session cancel`:
+ * id, status, and (only when present) exit code, error code, and error message. Session records
+ * use `errorCode`/`errorMessage` (never `error`) and have no top-level `summary` — see
+ * `SessionRecord` in services/api/src/db/types.ts.
+ */
+export function formatSessionLine(session) {
+  const parts = [session.id, session.status];
+  if (session.exitCode !== undefined && session.exitCode !== null) {
+    parts.push(`exitCode=${session.exitCode}`);
+  }
+  if (session.errorCode !== undefined) parts.push(`errorCode=${session.errorCode}`);
+  if (session.errorMessage !== undefined) parts.push(`errorMessage=${session.errorMessage}`);
+  return `${parts.join("  ")}\n`;
+}

package/src/cli/usage.js

@@ -15,13 +15,23 @@ Usage:
   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]
+  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]
   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]
+  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]
   auto-harness help | --help | -h
 
 Configuration:
@@ -53,7 +63,10 @@ Examples:
   auto-harness host list --online
   auto-harness host drain host-1
   auto-harness host inventory get host-1 --json > inventory.json
+  auto-harness host repo add host-1 repo-1 --path /repos/repo-1
   auto-harness host repo rm host-1 repo-1 --dry-run
+  auto-harness host smoke host-1 --repo-path /repos/repo-1 --provider claude
+  auto-harness repo add --name org/repo --url https://github.com/org/repo
   auto-harness repo list --all
   auto-harness repo rm repo-1
   auto-harness service-account list
@@ -62,5 +75,9 @@ Examples:
   aws ssm get-parameter --name /auto-harness/admin-password --with-decryption \\
     --query Parameter.Value --output text \\
     | auto-harness --admin-password-stdin service-account create --name ci --role operator --print-key
+  auto-harness session create --repo repo-1 --command claude-print --prompt "Review the diff" --wait
+  auto-harness session get session-1
+  auto-harness session logs session-1 --limit 200
+  auto-harness session cancel session-1
 `;
 }