auto-harness-client 0.7.0 → 0.8.0

package/README.md

@@ -375,6 +375,36 @@ Because the write replaces the whole record, omitting `providerAccounts` wipes t
 provider routing — always build the new document from a fresh `inventory get --json`, editing
 only what you mean to change.
 
+#### `auto-harness host repo add <hostId> <repositoryId> --path <path> [--worktree <id>=<path>]... [--default-branch <branch>] [--dry-run] [--json]`
+
+Attaches an already-registered repository (create it first with `auto-harness repo add`) to a
+host's inventory — the counterpart of `host repo rm`. Same safe read-modify-write shape:
+
+1. `GET /repositories/<repositoryId>` — a 404 fails with a clear message naming the id.
+   `--default-branch` defaults to that repository's own `defaultBranch` when omitted.
+2. `GET` the host's inventory. If this repository id is already attached, it fails (exit 1)
+   naming the path it is attached at — this command never overwrites an existing attachment;
+   remove it first with `host repo rm`.
+3. `--dry-run` prints what would be attached and exits without writing.
+4. Otherwise builds the new document as the record exactly as read, with the new entry appended
+   to `repositories` and the read `version` kept — every other field, including
+   `providerAccounts`, is preserved untouched.
+5. On a `409` (someone else wrote first) it re-reads and re-applies, up to 3 attempts total. If
+   the repository is now attached at the same path, that is treated as convergence (another
+   writer already did what this call wanted) rather than an error; a different path fails,
+   naming what is actually attached. Any other error status is not retried.
+6. On success it prints what was attached and the version transition (e.g. `version 29 → 30`).
+
+`--worktree <id>=<path>` is repeatable and adds one worktree entry per occurrence (split on the
+first `=`, so a path containing `=` still parses); a malformed value or a repeated id is a usage
+error (exit 2) before any request is made. Each becomes `{ id, name: id, path, labels: [] }` —
+`name` mirrors `id`, and the worktree's own name/slug shape is validated server-side.
+
+```sh
+auto-harness host repo add host-1 repo-1 --path /repos/repo-1 --dry-run
+auto-harness host repo add host-1 repo-1 --path /repos/repo-1 --worktree wt-1=/repos/repo-1/wt-1
+```
+
 #### `auto-harness host repo rm <hostId> <repositoryId> [--dry-run] [--json]`
 
 Detaches one repository from a host. This exists because the only prior way to do it was to
@@ -405,10 +435,98 @@ auto-harness host repo rm host-1 repo-1 --dry-run
 auto-harness host repo rm host-1 repo-1
 ```
 
+#### `auto-harness host smoke <hostId> --repo-path <path> --provider <id|name> [--provider <id|name>]... [--timeout <seconds>] [--json]`
+
+Proves a host can run a real provider-routed session end to end, then cleans up after itself —
+useful after standing up a new host, or after touching its execution profiles, without having to
+open the control plane UI. It never needs to be run against production to be trusted: the CI
+end-to-end suite (`e2e/control/cli-host-smoke.spec.ts`) exercises this exact command against a
+real API, a real in-process host daemon, and a real (`echo`-backed) provider on every change.
+
+**Preconditions this command cannot check itself:** `--repo-path` names a directory on the
+**host**, not on whatever machine runs this CLI — they may be different machines entirely — so
+this command never calls `existsSync` or otherwise inspects it locally. That path must already
+be a git repository with a clean `main` checkout, and its `.gitignore` must exclude
+`.worktrees/`, since this command attaches one worktree at `<repo-path>/.worktrees/<name>`,
+named after the throwaway repository. Worktree names are unique across the whole fleet, so each
+run uses a fresh name and concurrent smokes on different hosts never collide.
+
+What it does, in order, always tearing down in a `finally` no matter which step failed:
+
+1. **Create** a throwaway repository (`POST /repositories`) with a unique, valid (slug) name.
+   Its `url` is a syntactically valid but inert `https://example.test/<name>.git` placeholder —
+   the daemon dispatches sessions against the host-local path this same run attaches, never a
+   repository's `url`, so nothing ever needs to resolve or dial it.
+2. **Attach** it to `<hostId>`'s inventory via the same `attachRepository` read-modify-write
+   `host repo add` uses, with one worktree named after the repository.
+3. **For each `--provider`, in order** (accepts an id or a name, exactly like `session create`):
+   create a session targeting it with the prompt `Reply with exactly: <MARKER>` (`MARKER` is
+   random and unique per run), wait for it, then fetch one page of its logs. A provider `PASS`es
+   only if the session `completed` with `exitCode` `0` **and** its stdout contains `MARKER`.
+   - **The host racing its own inventory poll:** a host only learns about a newly attached
+     repository through its own periodic poll — there is no push-on-write — so the very first
+     session against the repository this command _just_ attached routinely loses that race in
+     any real deployment, not only here: the host rejects it with a `setup_failed` session whose
+     `errorMessage` is exactly `Unknown repository: <id>` (`services/host-daemon/src/
+worktree-manager.ts`), which the control plane never retries on its own. This command
+     recognizes that one exact, unambiguous shape and retries with it doubling backoff (up to 5
+     attempts, capped at 16s between attempts) — bounded by the same `--timeout` deadline as
+     everything else — before giving up and reporting it like any other failure. Any other
+     `setup_failed` (a real checkout/setup problem) is never retried.
+   - **Usage limits:** the control plane does not fail a session whose provider account hit its
+     usage limit — it requeues the session (`errorCode: "usage_limit"`) and puts the account on
+     cooldown instead (see `services/api/src/session-transition-planner.ts`'s
+     `planUsageLimit()`). This command checks for that on every poll (not only a status change,
+     since a requeued session's status can go right back to `"queued"` with no visible
+     transition) and fails that one provider immediately with "provider account hit its usage
+     limit" — it never sits out the rest of `--timeout` waiting for a cooldown to end.
+   - **On timeout**, the session is cancelled (this command owns it) and the provider fails with
+     a hint keyed off its last status: stuck in `queued` usually means no online host advertises
+     a ready execution profile for that provider's account (`HARNESS_EXECUTION_PROFILES`), or
+     nothing is running the scheduler.
+   - **A genuine polling failure** (a `getSession` network error or a `5xx`, not the usage-limit
+     or setup-failure shapes above) fails only that one provider with `session_wait_failed` — it
+     never aborts the run, so every remaining `--provider` still gets its own attempt. The
+     session is left for teardown's own safety net to cancel.
+4. **Teardown**, always: cancel any session this run created that isn't already terminal, detach
+   the repository (only if it was actually attached), then `DELETE` it. The delete retries a `409`
+   (the worktree/host-inventory projection the delete guard reads can lag the detach write
+   teardown just made) and a transient failure (`5xx`, or a network/timeout error) a few times
+   with a short backoff before giving up; once a transient failure has actually happened, a later
+   `404` is treated as success (the delete most likely landed and the response never arrived). If
+   a session could not be cancelled (anything other than a `409`, which just means it was already
+   terminal), or the repository is left behind, this command exits `1` and prints the exact
+   `session cancel` and/or `host repo rm`/`repo rm` commands needed to finish cleanup by hand.
+
+Exit `0` only when every provider passed **and** teardown itself succeeded; `1` otherwise (a
+malformed invocation is the usual usage-error exit `2`, before any of this runs). Progress
+(`ok`/`FAIL` per step) goes to stderr as it happens; stdout stays a clean final summary — one
+`PASS`/`FAIL` line per provider plus an overall line — or, with `--json`, the full structured
+result (`hostId`, `repositoryId`, `providers[]`, `teardown` — including any `uncancelledSessionIds`
+— `ok`).
+
+```sh
+auto-harness host smoke host-1 --repo-path /repos/repo-1 --provider claude
+auto-harness host smoke host-1 --repo-path /repos/repo-1 --provider claude --provider codex --timeout 600
+```
+
 ### `auto-harness repo <subcommand>`
 
 Repository CRUD, straight against the same routes `auto-harness api` would hit.
 
+#### `auto-harness repo add --name <name> --url <url> [--default-branch <branch>] [--json]`
+
+`POST /repositories`. The response is the created repository record itself — there is no
+`{ repository }` wrapper, matching the shape `GET /repositories/<id>` returns — so `--json`
+prints it verbatim. Human output is one line, `<id>  <name>`, mirroring `repo list`'s per-line
+format. `--default-branch` defaults server-side to `main` when omitted. The server also enforces
+uniqueness and URL/name format; a rejected value comes back as the normal `error:` line (exit 1)
+rather than a client-side re-check.
+
+```sh
+auto-harness repo add --name org/repo --url https://github.com/org/repo
+```
+
 #### `auto-harness repo list [--limit N] [--cursor C] [--all] [--json]`
 
 `GET /repositories`, printing one line per repository (id, name, and status/url when present).
@@ -490,3 +608,65 @@ KEY=$(auto-harness service-account create --name ci --role operator --print-key)
 ```sh
 auto-harness service-account rm svc-1
 ```
+
+### `auto-harness session <subcommand>`
+
+Session lifecycle for the operator CLI. `--provider`/`--command` accept either a catalog id or a
+name — see below.
+
+#### `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]`
+
+`POST /sessions`. Exactly one of `--provider`/`--command` is required. Each accepts either a
+catalog id or a name: the CLI lists the relevant catalog once and checks for an exact id match;
+on a miss it sends the value as `providerName`/`commandName` and lets `createSession()`'s own
+name resolution handle it — so an unresolvable or ambiguous name fails with the same
+`AutoHarnessError` (`UNKNOWN_PROVIDER_NAME`, `AMBIGUOUS_PROVIDER_NAME`, ...) documented above,
+never a separate "unknown id" error. `--timeout` defaults to `600` seconds (matching the
+create-session form's own default) since the server requires it but sets no default itself; the
+server's own ceiling (7 days) is enforced there, not duplicated here.
+
+With `--wait`, polls the new session until it reaches a terminal status (`completed`, `failed`,
+`cancelled`, or `timed_out`), printing each status change to **stderr** so stdout stays the final
+session record. `--wait-timeout <seconds>` bounds the wait (default: the session's own
+`--timeout`); on expiry the CLI prints that the session is still running and its id, then exits 1
+— it never cancels the session. Exit 0 only when the session `completed` with `exitCode` exactly
+`0`; every other terminal status, or a wait timeout, exits 1.
+
+```sh
+auto-harness session create --repo repo-1 --command claude-print --prompt "Review the diff" --wait
+```
+
+#### `auto-harness session get <sessionId> [--json]`
+
+`GET /sessions/<id>`, via the library's `getSession()`. Prints one line: id, status, and — only
+when present — `exitCode`, `errorCode`, `errorMessage` (session records use `errorCode`/
+`errorMessage`, never a top-level `error`, and `completedAt`, never `finishedAt`). `--json` prints
+the full record, including `result.summary` when the session set one.
+
+```sh
+auto-harness session get session-1
+```
+
+#### `auto-harness session logs <sessionId> [--limit N] [--cursor C] [--json]`
+
+`GET /sessions/<id>/logs` — a bounded page, printed once; this command never loops over every
+page (see `docs/plan.md` invariant 13). Unlike `repo list`/`host list`, the logs endpoint has no
+`nextCursor`; its only continuation knob is `since`, a whole ISO-8601 timestamp (exclusive),
+which this CLI exposes as `--cursor` for a pagination vocabulary consistent with the other list
+commands. A full page (`items.length === limit`, default `1000`) prints a hint to pass the last
+line's own timestamp as the next `--cursor` — which, because `since` excludes an entire
+timestamp rather than one row, also skips any other record sharing that exact timestamp. This is
+the bounded contract the endpoint offers today; there is no exact row cursor over REST.
+
+```sh
+auto-harness session logs session-1 --limit 200
+```
+
+#### `auto-harness session cancel <sessionId> [--json]`
+
+`POST /sessions/<id>/cancel`, via the library's `cancelSession()`. Prints the same one-line
+summary as `session get`.
+
+```sh
+auto-harness session cancel session-1
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-harness-client",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Dependency-free client for the Auto Harness automation API",
   "license": "MIT",
   "repository": {

package/src/cli/args.js

@@ -10,8 +10,18 @@ const REJECTED_API_KEY_MESSAGE =
  * every check below — the rejected `--api-key` flag, an unknown flag, a value flag missing its
  * value — only ever sees the flag name. This is what keeps a mistyped `--api-key=<secret>` (or
  * any other `--unknown=<secret>`) from echoing the secret back in a "unknown flag" error.
+ *
+ * `repeatableFlags` behave like `valueFlags` (same inline-`=`/next-argument value rule, same
+ * missing-value error) except every occurrence is collected into an array at `flags[name]`,
+ * rather than the last one winning — e.g. `--worktree a=/a --worktree b=/b` yields
+ * `flags["--worktree"] === ["a=/a", "b=/b"]`. A flag not given at all is still `undefined`, not
+ * an empty array, so callers can tell "none passed" from "passed with zero values" (impossible
+ * here, but keeps the convention consistent with `valueFlags`/`booleanFlags`).
  */
-export function parseFlags(argv, { valueFlags = [], booleanFlags = [] } = {}) {
+export function parseFlags(
+  argv,
+  { valueFlags = [], booleanFlags = [], repeatableFlags = [] } = {},
+) {
   const flags = {};
   const positionals = [];
   for (let i = 0; i < argv.length; i += 1) {
@@ -30,6 +40,12 @@ export function parseFlags(argv, { valueFlags = [], booleanFlags = [] } = {}) {
       flags[name] = value;
       continue;
     }
+    if (repeatableFlags.includes(name)) {
+      const value = inlineValue !== undefined ? inlineValue : argv[(i += 1)];
+      if (value === undefined) throw new CliUsageError(`${name} requires a value`);
+      (flags[name] ??= []).push(value);
+      continue;
+    }
     if (booleanFlags.includes(name)) {
       if (inlineValue !== undefined) throw new CliUsageError(`${name} does not take a value`);
       flags[name] = true;

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/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/host-repo-add.js

@@ -0,0 +1,81 @@
+import { AutoHarnessError } from "../../index.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 { attachRepository } from "./attach-repository.js";
+import { parseWorktreeFlags } from "./parse-worktree-flag.js";
+
+const USAGE =
+  "usage: auto-harness host repo add <hostId> <repositoryId> --path <path> " +
+  "[--worktree <id>=<path>]... [--default-branch <branch>] [--dry-run] [--json]";
+
+/**
+ * Attaches an existing repository to a host's inventory — the counterpart of `host repo rm`.
+ * A thin wrapper: flag parsing and presentation live here, but the actual read-modify-write
+ * lives in `attachRepository` (its own module, reused by a later `host smoke` command).
+ */
+export async function runHostRepoAdd(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--path", "--default-branch"],
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--dry-run", "--json"],
+    repeatableFlags: ["--worktree"],
+  });
+  const [hostId, repositoryId] = positionals;
+  if (!hostId || !repositoryId || positionals.length > 2 || !flags["--path"]) {
+    throw new CliUsageError(USAGE);
+  }
+  pathSegment(hostId, "hostId"); // validate before createClient, which may log in
+  pathSegment(repositoryId, "repositoryId");
+  const worktrees = parseWorktreeFlags(flags["--worktree"] ?? []);
+  const client = await createClient(flags, io);
+  const repository = await getRepositoryOrFail(client, repositoryId);
+  const entry = {
+    id: repositoryId,
+    path: flags["--path"],
+    defaultBranch: flags["--default-branch"] ?? repository.defaultBranch,
+    worktrees,
+  };
+  const result = await attachRepository(client, hostId, entry, {
+    dryRun: Boolean(flags["--dry-run"]),
+  });
+  printResult(io, flags, result);
+  return 0;
+}
+
+/** A 404 here means the id is simply wrong — a clearer message than the generic `error: ...
+ * (HTTP 404, NOT_FOUND)` line `reportError` would otherwise print. Any other status (a scoped
+ * key that cannot see this repository, a transient failure) is left to the normal error path. */
+async function getRepositoryOrFail(client, repositoryId) {
+  try {
+    return await client.request(`/repositories/${pathSegment(repositoryId, "repositoryId")}`);
+  } catch (error) {
+    if (error instanceof AutoHarnessError && error.status === 404) {
+      throw new Error(`repository ${repositoryId} not found`, { cause: error });
+    }
+    throw error;
+  }
+}
+
+function printResult(io, flags, info) {
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify(info, null, 2)}\n`);
+    return;
+  }
+  if (info.convergedElsewhere) {
+    io.stdout.write(
+      `repository ${info.repository.id} was already attached to host ${info.hostId} by ` +
+        `another writer at the same path (now at version ${info.toVersion})\n`,
+    );
+    return;
+  }
+  const verb = info.dryRun ? "would attach" : "attached";
+  const lines = [
+    `${verb} repository ${info.repository.id} (${info.repository.path}) to host ${info.hostId}`,
+  ];
+  if (info.worktreeIds.length > 0) {
+    lines.push(`  worktrees: ${info.worktreeIds.join(", ")}`);
+  }
+  if (!info.dryRun) lines.push(`version ${info.fromVersion} → ${info.toVersion}`);
+  io.stdout.write(`${lines.join("\n")}\n`);
+}

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

@@ -1,19 +1,15 @@
-import { AutoHarnessError } from "../../index.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 { detachRepository } from "./detach-repository.js";
 
 const USAGE = "usage: auto-harness host repo rm <hostId> <repositoryId> [--dry-run] [--json]";
-const MAX_ATTEMPTS = 3;
 
 /**
- * Detaches one repository from a host's inventory as a safe read-modify-write: 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, with the read `version` kept. On a 409 (someone else
- * wrote first) it re-reads and re-applies, up to `MAX_ATTEMPTS` PUTs total; any other status is
- * not retried.
+ * Detaches one repository from a host's inventory — the counterpart of `host repo add`. A thin
+ * wrapper: flag parsing and presentation live here, but the actual safe read-modify-write lives
+ * in `detachRepository` (its own module, reused by `host smoke`'s teardown).
  */
 export async function runHostRepoRm(argv, io) {
   const { flags, positionals } = parseFlags(argv, {
@@ -24,84 +20,11 @@ export async function runHostRepoRm(argv, io) {
   if (!hostId || !repositoryId || positionals.length > 2) throw new CliUsageError(USAGE);
   pathSegment(hostId, "hostId"); // validate before createClient, which may log in
   const client = await createClient(flags, io);
-  const record = await getInventory(client, hostId);
-  const removal = extractRepository(record, hostId, repositoryId);
-  if (flags["--dry-run"]) {
-    printResult(io, flags, { dryRun: true, hostId, ...removal });
-    return 0;
-  }
-  return removeWithRetry(client, io, flags, hostId, repositoryId, record, removal);
-}
-
-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 };
-}
-
-async function removeWithRetry(client, io, flags, 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),
-      });
-      printResult(io, flags, {
-        dryRun: false,
-        hostId,
-        repository: current.repository,
-        worktreeIds: current.worktreeIds,
-        fromVersion,
-        toVersion: result?.version,
-      });
-      return 0;
-    } 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) {
-        printResult(io, flags, {
-          convergedElsewhere: true,
-          hostId,
-          repository: current.repository,
-          worktreeIds: current.worktreeIds,
-          toVersion: currentRecord.version,
-        });
-        return 0;
-      }
-      current = next;
-    }
-  }
-  /* v8 ignore next 2 -- the loop above always returns or throws before falling out */
-  return 1;
+  const result = await detachRepository(client, hostId, repositoryId, {
+    dryRun: Boolean(flags["--dry-run"]),
+  });
+  printResult(io, flags, result);
+  return 0;
 }
 
 function printResult(io, flags, info) {