auto-harness-client 0.6.0 → 0.8.0

package/src/cli/cli-errors.js

@@ -0,0 +1,16 @@
+/** A malformed invocation: a bad flag, a missing/invalid argument, invalid JSON input. Exit 2. */
+export class CliUsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliUsageError";
+  }
+}
+
+/** Configuration could not be resolved: no base URL, an unreadable key file, an invalid
+ * baseUrl/apiKey combination rejected by `AutoHarnessClient` itself. Exit 2. */
+export class CliConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliConfigError";
+  }
+}

package/src/cli/commands/api.js

@@ -0,0 +1,91 @@
+import { checkAdminLoginUsage } from "../admin-login.js";
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+import { readStdin } from "../read-stdin.js";
+
+const USAGE = "usage: auto-harness api <METHOD> <path> [--body <json> | --body-file <path|->]";
+
+// Methods the control-plane API uses. An explicit list rather than HTTP's token grammar: Fetch
+// also rejects valid tokens (CONNECT, TRACE, TRACK), and a typo should be a usage error (exit 2)
+// before anything is sent, not a Fetch TypeError surfacing as an API failure (exit 1).
+const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]);
+
+// Segments the WHATWG URL parser resolves as "." and "..", percent-encoded forms included
+// (compared case-insensitively). Letting one through would resolve the request outside
+// `/api/v1` — e.g. `/../../health` becomes `/health` — with the bearer token still attached.
+const DOT_SEGMENTS = new Set([".", "..", "%2e", "%2e%2e", ".%2e", "%2e."]);
+
+/**
+ * Generic escape hatch for any route. Prints the response's parsed JSON, pretty-printed, on
+ * success; prints nothing for a 204 or otherwise empty body. Deliberately does not filter the
+ * response the way `whoami`/`doctor` do — an operator asking for `GET /auth/me` through this
+ * command gets the raw body, hashes included, because filtering an explicit raw-response request
+ * would defeat the point of having an escape hatch at all.
+ */
+export async function runApi(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--body", "--body-file"],
+    booleanFlags: GLOBAL_BOOLEAN_FLAGS,
+  });
+  const [method, path] = positionals;
+  if (!method || !path || positionals.length > 2) throw new CliUsageError(USAGE);
+  if (flags["--body"] !== undefined && flags["--body-file"] !== undefined) {
+    throw new CliUsageError("--body and --body-file are mutually exclusive");
+  }
+  const httpMethod = method.toUpperCase();
+  if (!METHODS.has(httpMethod)) {
+    throw new CliUsageError(
+      `unsupported HTTP method ${method}; use one of ${[...METHODS].join(", ")}`,
+    );
+  }
+  const apiPath = normalizeApiPath(path);
+  // Both this command's own `--body-file -` and `--admin-password-stdin` need stdin; catch the
+  // conflict before reading either, rather than letting one silently drain the other's input.
+  const stdinClaimedBy = flags["--body-file"] === "-" ? "api --body-file -" : undefined;
+  checkAdminLoginUsage(flags, io.env, stdinClaimedBy);
+  const body = await resolveBody(flags, io);
+  const client = await createClient(flags, io);
+  const result = await client.request(apiPath, {
+    method: httpMethod,
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+  if (result !== undefined) io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}
+
+async function resolveBody(flags, io) {
+  let text;
+  if (flags["--body"] !== undefined) text = flags["--body"];
+  else if (flags["--body-file"] === "-") text = await readStdin(io.stdin);
+  else if (flags["--body-file"] !== undefined) {
+    text = await readBodyFile(flags["--body-file"], io.readFile);
+  } else return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CliUsageError("--body/--body-file must contain valid JSON");
+  }
+}
+
+async function readBodyFile(path, readFile) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    throw new CliUsageError(`could not read --body-file ${path}: ${error.message}`);
+  }
+}
+
+/** The client already prefixes every path with `/api/v1`, so accept both `/hosts` and
+ * `/api/v1/hosts` by stripping a leading `/api/v1` segment before handing the path along.
+ * Rejects any dot segment in the path part (the query string is not a path), splitting on `\`
+ * as well as `/` because an https URL treats a backslash as a segment separator. */
+function normalizeApiPath(path) {
+  const withLeadingSlash = path.startsWith("/") ? path : `/${path}`;
+  const stripped = withLeadingSlash.replace(/^\/api\/v1(?=\/|$)/, "");
+  const pathPart = stripped.split(/[?#]/, 1)[0];
+  if (pathPart.split(/[/\\]/).some((segment) => DOT_SEGMENTS.has(segment.toLowerCase()))) {
+    throw new CliUsageError(`path must not contain "." or ".." segments: ${path}`);
+  }
+  return stripped === "" ? "/" : stripped;
+}

package/src/cli/commands/attach-repository.js

@@ -0,0 +1,117 @@
+import { AutoHarnessError } from "../../index.js";
+import { pathSegment } from "../path-segment.js";
+
+const MAX_ATTEMPTS = 3;
+
+/** GET the current inventory record for a host — shared by the pre-write "already attached"
+ * check, the dry-run preview, and every retry's re-read, so all three see the same document. */
+function getInventory(client, hostId) {
+  return client.request(`/hosts/${pathSegment(hostId, "hostId")}/inventory`);
+}
+
+function findAttachedRepository(record, repositoryId) {
+  return (record.repositories ?? []).find((repo) => repo.id === repositoryId);
+}
+
+/**
+ * Attaches `entry` (an inventory repository entry — see `parseWorktreeFlags` and
+ * `host-repo-add.js` for how it is built) to a host's inventory as a safe read-modify-write,
+ * mirroring `host-repo-rm.js`'s remove flow: GET the full record, add only the new entry to
+ * `repositories`, and PUT back everything else — including `providerAccounts` — exactly as
+ * read, keeping the read `version`. A repository already attached to the host is never
+ * overwritten; the caller must remove it first. On a 409 (someone else wrote first) this
+ * re-reads and re-applies, up to `MAX_ATTEMPTS` PUTs total; any other status is not retried.
+ *
+ * `{ dryRun: true }` does the same read and "already attached" check but returns before ever
+ * writing, so `host repo add --dry-run` and a real attach can never disagree about whether the
+ * attach would succeed. Exported (rather than folded into the command) because a later
+ * `host smoke` command reuses this exact logic.
+ */
+export async function attachRepository(client, hostId, entry, { dryRun = false } = {}) {
+  const record = await getInventory(client, hostId);
+  const existing = findAttachedRepository(record, entry.id);
+  if (existing) {
+    throw new Error(
+      `repository ${entry.id} is already attached to host ${hostId} at ${existing.path}`,
+    );
+  }
+  if (dryRun) {
+    return {
+      attached: false,
+      dryRun: true,
+      convergedElsewhere: false,
+      hostId,
+      repository: entry,
+      worktreeIds: entry.worktrees.map((worktree) => worktree.id),
+      fromVersion: record.version ?? 0,
+    };
+  }
+  return attachWithRetry(client, hostId, entry, record);
+}
+
+async function attachWithRetry(client, hostId, entry, record) {
+  let currentRecord = record;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    const fromVersion = currentRecord.version ?? 0;
+    const document = {
+      ...currentRecord,
+      repositories: [...(currentRecord.repositories ?? []), entry],
+      version: fromVersion,
+    };
+    try {
+      const result = await client.request(`/hosts/${pathSegment(hostId, "hostId")}/inventory`, {
+        method: "PUT",
+        body: JSON.stringify(document),
+      });
+      return {
+        attached: true,
+        dryRun: false,
+        convergedElsewhere: false,
+        hostId,
+        repository: entry,
+        worktreeIds: entry.worktrees.map((worktree) => worktree.id),
+        fromVersion,
+        toVersion: result?.version,
+      };
+    } catch (error) {
+      const conflict = error instanceof AutoHarnessError && error.status === 409;
+      if (!conflict) throw error;
+      if (attempt === MAX_ATTEMPTS) {
+        throw new Error(
+          `inventory for host ${hostId} kept changing; gave up after ${MAX_ATTEMPTS} attempts`,
+          { cause: error },
+        );
+      }
+      currentRecord = await getInventory(client, hostId);
+      const convergence = reconcileConflict(currentRecord, hostId, entry);
+      if (convergence) return convergence;
+    }
+  }
+  /* v8 ignore next 2 -- the loop above always returns or throws before falling out */
+  return undefined;
+}
+
+/** After a 409, someone else changed the inventory first. If they attached this same repository
+ * at the same path, that is the outcome this call wanted — report convergence rather than
+ * erroring, exactly like `host repo rm`'s "already removed by another writer" case. A different
+ * path is a real conflict: report it using the record now on the server, not our own intent, so
+ * the error names what is actually attached. Neither case retries the loop again. */
+function reconcileConflict(currentRecord, hostId, entry) {
+  const existing = findAttachedRepository(currentRecord, entry.id);
+  if (!existing) return undefined;
+  if (existing.path !== entry.path) {
+    throw new Error(
+      `repository ${entry.id} was attached to host ${hostId} at ${existing.path} by another ` +
+        "writer while this command was adding it",
+    );
+  }
+  return {
+    attached: true,
+    dryRun: false,
+    convergedElsewhere: true,
+    hostId,
+    repository: existing,
+    worktreeIds: (existing.worktrees ?? []).map((worktree) => worktree.id),
+    toVersion: currentRecord.version,
+  };
+}

package/src/cli/commands/dependency-conflict.js

@@ -0,0 +1,15 @@
+import { AutoHarnessError } from "../../index.js";
+
+/** True for a refused delete: a 409 CONFLICT whose body carries `dependencies` (see
+ * `AutoHarnessClient#request`, which puts the whole `error` body on `AutoHarnessError#details`).
+ * Shared by `repo rm` and `service-account rm`, which both handle this status themselves rather
+ * than letting the generic `reportError` print it as an opaque JSON blob. */
+export function isDependencyConflict(error) {
+  return error instanceof AutoHarnessError && error.status === 409;
+}
+
+/** The dependency array from a conflict's error body, or `[]` if absent/malformed. */
+export function conflictDependencies(error) {
+  const dependencies = error.details?.dependencies;
+  return Array.isArray(dependencies) ? dependencies : [];
+}

package/src/cli/commands/detach-repository.js

@@ -0,0 +1,109 @@
+import { AutoHarnessError } from "../../index.js";
+import { pathSegment } from "../path-segment.js";
+
+const MAX_ATTEMPTS = 3;
+
+/** GET the current inventory record for a host — shared by the pre-write extraction, the
+ * dry-run preview, and every retry's re-read, so all three see the same document. */
+function getInventory(client, hostId) {
+  return client.request(`/hosts/${pathSegment(hostId, "hostId")}/inventory`);
+}
+
+/** Finds the repository by id. By default throws (exit 1) listing what is actually attached;
+ * pass `required: false` to get `null` instead — used on a retry's re-read, where the
+ * repository being gone already means someone else's write reached the same goal. */
+function extractRepository(record, hostId, repositoryId, { required = true } = {}) {
+  const repositories = record.repositories ?? [];
+  const repository = repositories.find((repo) => repo.id === repositoryId);
+  if (!repository) {
+    if (!required) return null;
+    const attached = repositories.map((repo) => repo.id);
+    throw new Error(
+      `repository ${repositoryId} is not attached to host ${hostId}; attached repositories: ` +
+        (attached.length > 0 ? attached.join(", ") : "(none)"),
+    );
+  }
+  const worktreeIds = (repository.worktrees ?? []).map((worktree) => worktree.id);
+  const remaining = repositories.filter((repo) => repo.id !== repositoryId);
+  return { repository, worktreeIds, remaining };
+}
+
+/**
+ * Detaches one repository from a host's inventory as a safe read-modify-write, mirroring
+ * `attach-repository.js`'s attach flow: GET the full record, remove only the target repository
+ * (its worktrees go with it — that is a projection of the repository, not a separate thing to
+ * delete), and PUT back everything else — including `providerAccounts` — exactly as read,
+ * keeping the read `version`. On a 409 (someone else wrote first) this re-reads and re-applies,
+ * up to `MAX_ATTEMPTS` PUTs total; any other status is not retried.
+ *
+ * `{ dryRun: true }` does the same read and lookup but returns before ever writing, so
+ * `host repo rm --dry-run` and a real detach can never disagree about what would be removed.
+ * Exported (rather than folded into the command) because `host smoke` reuses this exact logic
+ * for its own teardown.
+ */
+export async function detachRepository(client, hostId, repositoryId, { dryRun = false } = {}) {
+  const record = await getInventory(client, hostId);
+  const removal = extractRepository(record, hostId, repositoryId);
+  if (dryRun) {
+    return {
+      detached: false,
+      dryRun: true,
+      convergedElsewhere: false,
+      hostId,
+      repository: removal.repository,
+      worktreeIds: removal.worktreeIds,
+      fromVersion: record.version ?? 0,
+    };
+  }
+  return removeWithRetry(client, hostId, repositoryId, record, removal);
+}
+
+async function removeWithRetry(client, hostId, repositoryId, record, removal) {
+  let currentRecord = record;
+  let current = removal;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    const fromVersion = currentRecord.version ?? 0;
+    const document = { ...currentRecord, repositories: current.remaining, version: fromVersion };
+    try {
+      const result = await client.request(`/hosts/${pathSegment(hostId, "hostId")}/inventory`, {
+        method: "PUT",
+        body: JSON.stringify(document),
+      });
+      return {
+        detached: true,
+        dryRun: false,
+        convergedElsewhere: false,
+        hostId,
+        repository: current.repository,
+        worktreeIds: current.worktreeIds,
+        fromVersion,
+        toVersion: result?.version,
+      };
+    } catch (error) {
+      const conflict = error instanceof AutoHarnessError && error.status === 409;
+      if (!conflict) throw error;
+      if (attempt === MAX_ATTEMPTS) {
+        throw new Error(
+          `inventory for host ${hostId} kept changing; gave up after ${MAX_ATTEMPTS} attempts`,
+          { cause: error },
+        );
+      }
+      currentRecord = await getInventory(client, hostId);
+      const next = extractRepository(currentRecord, hostId, repositoryId, { required: false });
+      if (!next) {
+        return {
+          detached: true,
+          dryRun: false,
+          convergedElsewhere: true,
+          hostId,
+          repository: current.repository,
+          worktreeIds: current.worktreeIds,
+          toVersion: currentRecord.version,
+        };
+      }
+      current = next;
+    }
+  }
+  /* v8 ignore next 2 -- the loop above always returns or throws before falling out */
+  return undefined;
+}

package/src/cli/commands/doctor.js

@@ -0,0 +1,164 @@
+import { AutoHarnessClient, AutoHarnessError } from "../../index.js";
+import { loginAsAdmin } from "../admin-login.js";
+import { allowlistPrincipal } from "../allowlist.js";
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS, resolveConfig } from "../config.js";
+
+// A raw API Gateway endpoint bypasses CloudFront, which is what injects the ingress token; the
+// host daemon's own usage text says never to use one (see cli-usage.ts).
+const EXECUTE_API_HOST = /\.execute-api\.[^.]+\.amazonaws\.com$/i;
+
+// Matches `AutoHarnessClient`'s default `requestTimeoutMs`.
+const REACHABILITY_TIMEOUT_MS = 30_000;
+
+/** Runs the url/reachability/auth checks and prints one `<status> <name>: <reason>` line each.
+ * Returns 1 if any check `fail`s, else 0 — a `warn` never fails the overall run. */
+export async function runDoctor(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: GLOBAL_BOOLEAN_FLAGS,
+  });
+  if (positionals.length > 0) {
+    throw new CliUsageError(`doctor takes no arguments; received: ${positionals.join(" ")}`);
+  }
+  const config = await resolveConfig(flags, io);
+  const checks = [
+    checkUrlShape(config.baseUrl, config.allowInsecureHttp),
+    await checkReachability(config.baseUrl, io.fetch, io.timeoutSignal ?? AbortSignal.timeout),
+    await checkAuth(config, io),
+  ];
+  for (const check of checks) io.stdout.write(formatCheck(check));
+  return checks.some((check) => check.status === "fail") ? 1 : 0;
+}
+
+/** `AutoHarnessClient` strips a trailing `/api/v1` from `baseUrl` itself; `/health` lives at the
+ * site root, so this mirrors that same normalization for the raw (non-`client.request`) fetch. */
+function siteOrigin(baseUrl) {
+  return baseUrl.replace(/\/$/, "").replace(/\/api\/v1$/, "");
+}
+
+function checkUrlShape(baseUrl, allowInsecureHttp) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    return { name: "url", status: "fail", message: `${baseUrl} is not a valid URL` };
+  }
+  if (url.protocol === "http:" && !allowInsecureHttp) {
+    return {
+      name: "url",
+      status: "fail",
+      message: "baseUrl uses http:// (pass --allow-insecure-http only for local/loopback dev)",
+    };
+  }
+  if (EXECUTE_API_HOST.test(url.hostname)) {
+    return {
+      name: "url",
+      status: "warn",
+      message:
+        "raw API Gateway URL bypasses CloudFront, which injects the ingress token, so " +
+        "requests will be rejected; use the CloudFront WebUrl from the deploy output instead",
+    };
+  }
+  return { name: "url", status: "ok", message: `using ${baseUrl}` };
+}
+
+/** `timeoutSignal(ms)` defaults to `AbortSignal.timeout`; tests inject one they can abort,
+ * since a real 30-second timer cannot be fast-forwarded. */
+async function checkReachability(baseUrl, fetchFn, timeoutSignal) {
+  const url = `${siteOrigin(baseUrl)}/health`;
+  // Bounded like `AutoHarnessClient`'s default, and it covers the body read below as well as
+  // the connection — without it a stalled server hangs doctor forever instead of failing.
+  const signal = timeoutSignal(REACHABILITY_TIMEOUT_MS);
+  let response;
+  let body;
+  try {
+    response = await fetchFn(url, { signal });
+    if (response.status === 200) {
+      // A non-JSON body is a failed check, but a timeout mid-body must surface as the timeout
+      // rather than be swallowed here — the same rule `AutoHarnessClient#request` applies.
+      body = await response.json().catch((error) => {
+        if (signal.aborted) throw error;
+        return undefined;
+      });
+    }
+  } catch (error) {
+    return {
+      name: "reachability",
+      status: "fail",
+      message: `GET /health failed: ${error.message}`,
+    };
+  }
+  if (response.status !== 200) {
+    return {
+      name: "reachability",
+      status: "fail",
+      message: `GET /health returned HTTP ${response.status}`,
+    };
+  }
+  if (!body || body.ok !== true) {
+    return {
+      name: "reachability",
+      status: "fail",
+      message: 'GET /health did not return {"ok":true}',
+    };
+  }
+  return { name: "reachability", status: "ok", message: "control plane is reachable" };
+}
+
+/**
+ * In admin mode the login itself is attempted here, inside this check's own try/catch — not
+ * eagerly in `resolveConfig` — so a bad admin password only fails this one check and still
+ * lets the url/reachability checks above it print, the same way a rejected API key does.
+ */
+async function checkAuth(config, io) {
+  if (!config.apiKey && !config.adminMode) {
+    return {
+      name: "auth",
+      status: "warn",
+      message: "no API key configured; only unauthenticated checks ran",
+    };
+  }
+  let fetchFn = io.fetch;
+  if (config.adminMode) {
+    try {
+      fetchFn = (
+        await loginAsAdmin(io, config.baseUrl, config.adminUsername, config.allowInsecureHttp)
+      ).fetch;
+    } catch (error) {
+      return { name: "auth", status: "fail", message: error.message };
+    }
+  }
+  let client;
+  try {
+    client = new AutoHarnessClient({
+      baseUrl: config.baseUrl,
+      apiKey: config.apiKey,
+      fetch: fetchFn,
+      allowInsecureHttp: config.allowInsecureHttp,
+    });
+  } catch (error) {
+    return { name: "auth", status: "fail", message: error.message };
+  }
+  try {
+    const principal = allowlistPrincipal(await client.request("/auth/me"));
+    const role = principal.role ?? "unknown";
+    const capabilities = Array.isArray(principal.capabilities)
+      ? principal.capabilities.join(", ")
+      : "none";
+    const message = config.adminMode
+      ? `authenticated as ${principal.username} (role ${role}; capabilities: ${capabilities})`
+      : `authenticated as role ${role} (capabilities: ${capabilities})`;
+    return { name: "auth", status: "ok", message };
+  } catch (error) {
+    if (error instanceof AutoHarnessError && error.status === 401) {
+      return { name: "auth", status: "fail", message: "API key rejected" };
+    }
+    return { name: "auth", status: "fail", message: `GET /auth/me failed: ${error.message}` };
+  }
+}
+
+function formatCheck({ status, name, message }) {
+  return `${status} ${name}: ${message}\n`;
+}

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

@@ -0,0 +1,22 @@
+import { runHostIdPostAction } from "./host-post-action.js";
+
+/** `POST /hosts/drain` with `{ hostId }` in the body. */
+export async function runHostDrain(argv, io) {
+  return runHostIdPostAction(argv, io, {
+    commandName: "drain",
+    path: "/hosts/drain",
+    onSuccess: (result, hostId, flags) => {
+      if (flags["--json"]) {
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+      }
+      const runningSessionIds = result?.runningSessionIds ?? [];
+      io.stdout.write(
+        `host ${hostId} is draining (${runningSessionIds.length} session(s) still running)\n`,
+      );
+      if (runningSessionIds.length > 0) {
+        io.stdout.write(`${runningSessionIds.map((id) => `  ${id}`).join("\n")}\n`);
+      }
+    },
+  });
+}

package/src/cli/commands/host-inventory-get.js

@@ -0,0 +1,40 @@
+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 host inventory get <hostId> [--json]";
+
+/** `GET /hosts/<hostId>/inventory`. */
+export async function runHostInventoryGet(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  const [hostId] = positionals;
+  if (!hostId || positionals.length > 1) throw new CliUsageError(USAGE);
+  const hostSegment = pathSegment(hostId, "hostId");
+  const client = await createClient(flags, io);
+  const record = await client.request(`/hosts/${hostSegment}/inventory`);
+  io.stdout.write(
+    flags["--json"] ? `${JSON.stringify(record, null, 2)}\n` : formatInventory(record),
+  );
+  return 0;
+}
+
+function formatInventory(record) {
+  const lines = [`version: ${record.version ?? 0}`];
+  const repositories = record.repositories ?? [];
+  if (repositories.length === 0) {
+    lines.push("repositories: (none)");
+  } else {
+    lines.push("repositories:");
+    for (const repository of repositories) {
+      const worktreeCount = (repository.worktrees ?? []).length;
+      const label = worktreeCount === 1 ? "worktree" : "worktrees";
+      lines.push(`  ${repository.id}  ${repository.path}  (${worktreeCount} ${label})`);
+    }
+  }
+  lines.push(`provider accounts: ${(record.providerAccounts ?? []).length}`);
+  return `${lines.join("\n")}\n`;
+}

package/src/cli/commands/host-inventory-set.js

@@ -0,0 +1,66 @@
+import { checkAdminLoginUsage } from "../admin-login.js";
+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 { readStdin } from "../read-stdin.js";
+
+const USAGE = "usage: auto-harness host inventory set <hostId> --file <path|->";
+
+const MISSING_VERSION_MESSAGE =
+  "the document has no integer `version` field: omitting it silently disables optimistic " +
+  "concurrency on the server, so a concurrent change could be overwritten with no error; " +
+  "start from `auto-harness host inventory get <hostId> --json` and edit that";
+
+/**
+ * `PUT /hosts/<hostId>/inventory`. The PUT is authoritative — it replaces the whole record —
+ * so this sends the file/stdin text verbatim as the request body rather than re-serializing a
+ * parsed copy; it only parses to validate that the document is a JSON object carrying the
+ * integer `version` the server needs for optimistic concurrency.
+ */
+export async function runHostInventorySet(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--file"],
+    booleanFlags: GLOBAL_BOOLEAN_FLAGS,
+  });
+  const [hostId] = positionals;
+  if (!hostId || positionals.length > 1 || !flags["--file"]) throw new CliUsageError(USAGE);
+  const hostSegment = pathSegment(hostId, "hostId");
+  // Both this command's own `--file -` and `--admin-password-stdin` need stdin; catch the
+  // conflict before reading either, rather than letting one silently drain the other's input.
+  const stdinClaimedBy = flags["--file"] === "-" ? "host inventory set --file -" : undefined;
+  checkAdminLoginUsage(flags, io.env, stdinClaimedBy);
+  const text = await readDocument(flags["--file"], io);
+  validateDocument(text);
+  const client = await createClient(flags, io);
+  const result = await client.request(`/hosts/${hostSegment}/inventory`, {
+    method: "PUT",
+    body: text,
+  });
+  io.stdout.write(`inventory for host ${hostId} set to version ${result?.version}\n`);
+  return 0;
+}
+
+async function readDocument(path, io) {
+  if (path === "-") return readStdin(io.stdin);
+  try {
+    return await io.readFile(path, "utf8");
+  } catch (error) {
+    throw new CliUsageError(`could not read --file ${path}: ${error.message}`);
+  }
+}
+
+function validateDocument(text) {
+  let document;
+  try {
+    document = JSON.parse(text);
+  } catch {
+    throw new CliUsageError("--file must contain valid JSON");
+  }
+  if (!document || typeof document !== "object" || Array.isArray(document)) {
+    throw new CliUsageError("--file must contain a JSON object");
+  }
+  if (!Number.isInteger(document.version)) {
+    throw new CliUsageError(MISSING_VERSION_MESSAGE);
+  }
+}

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

@@ -0,0 +1,15 @@
+import { CliUsageError } from "../cli-errors.js";
+import { runHostInventoryGet } from "./host-inventory-get.js";
+import { runHostInventorySet } from "./host-inventory-set.js";
+
+const USAGE = `usage: auto-harness host inventory <get|set> ...
+  auto-harness host inventory get <hostId> [--json]
+  auto-harness host inventory set <hostId> --file <path|->`;
+
+/** Dispatches `host inventory <get|set>`. */
+export async function runHostInventory(argv, io) {
+  const [action, ...rest] = argv;
+  if (action === "get") return runHostInventoryGet(rest, io);
+  if (action === "set") return runHostInventorySet(rest, io);
+  throw new CliUsageError(USAGE);
+}