auto-harness-client 0.7.0 → 0.8.0

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

@@ -1,11 +1,16 @@
 import { CliUsageError } from "../cli-errors.js";
+import { runHostRepoAdd } from "./host-repo-add.js";
 import { runHostRepoRm } from "./host-repo-rm.js";
 
-const USAGE = "usage: auto-harness host repo rm <hostId> <repositoryId> [--dry-run] [--json]";
+const USAGE = `usage: auto-harness host repo <subcommand> ...
+  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]`;
 
-/** Dispatches `host repo <rm>`. */
+/** Dispatches `host repo <add|rm>`. */
 export async function runHostRepo(argv, io) {
   const [action, ...rest] = argv;
+  if (action === "add") return runHostRepoAdd(rest, io);
   if (action === "rm") return runHostRepoRm(rest, io);
   throw new CliUsageError(USAGE);
 }

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

@@ -0,0 +1,30 @@
+/** One progress line per step, as it happens — always stderr, so stdout stays a clean final
+ * summary (mirrors `session create --wait`'s status-change lines going to stderr). */
+export function step(io, ok, message) {
+  io.stderr.write(`${ok ? "ok" : "FAIL"}  ${message}\n`);
+}
+
+/**
+ * The clean final summary on stdout: `--json` prints the full structured `result` verbatim;
+ * otherwise one `PASS`/`FAIL` line per provider (only ever empty when repo create/attach itself
+ * failed, in which case `result.setupError` is printed instead), then one overall line.
+ */
+export function printSummary(io, flags, result) {
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  if (result.setupError) {
+    io.stdout.write(`FAIL  setup: ${result.setupError}\n`);
+  }
+  for (const provider of result.providers) {
+    const detail = provider.message ? `: ${provider.message}` : "";
+    io.stdout.write(`${provider.pass ? "PASS" : "FAIL"}  ${provider.provider}${detail}\n`);
+  }
+  const passed = result.providers.filter((provider) => provider.pass).length;
+  if (result.providers.length > 0) {
+    io.stdout.write(`${passed}/${result.providers.length} providers passed\n`);
+  }
+  io.stdout.write(`teardown ${result.teardown.ok ? "ok" : "FAILED"}\n`);
+  io.stdout.write(`host smoke ${result.ok ? "PASSED" : "FAILED"} for host ${result.hostId}\n`);
+}

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

@@ -0,0 +1,77 @@
+import { waitForSession } from "../wait-for-session.js";
+
+/** Thrown from the wrapped `getSession` below to escape `waitForSession`'s loop the instant a
+ * usage-limit requeue is observed, rather than waiting out the rest of `timeoutMs`. */
+class UsageLimitSignal extends Error {
+  constructor(session) {
+    super("usage_limit");
+    this.session = session;
+  }
+}
+
+/** `client.getSession` wrapped to check *every* poll for `errorCode === "usage_limit"`, not
+ * only a status *change* — see `waitForSmokeSession`'s doc comment for why that distinction
+ * matters here. */
+function usageLimitWatchedClient(client) {
+  return {
+    getSession: async (id) => {
+      const session = await client.getSession(id);
+      if (session.errorCode === "usage_limit") throw new UsageLimitSignal(session);
+      return session;
+    },
+  };
+}
+
+/**
+ * Wraps `waitForSession` so `host smoke` fails a provider fast when the control plane reports
+ * `errorCode: "usage_limit"`, instead of sitting out the whole `--timeout`.
+ * `session-transition-planner.ts`'s `planUsageLimit()` *requeues* a usage-limited session
+ * (status goes back to `"queued"`, cooldown applied to the account) rather than failing it
+ * outright, so a plain wait-for-terminal-status loop would never notice until the timeout
+ * elapsed. This is checked on every single poll, not on `waitForSession`'s own `onStatus`
+ * (which only fires on a status *change*) — a session that never even reaches `"running"`
+ * (requeued immediately, or its account was already cooling down when created) gets
+ * `errorCode` set with no status transition to hang the check off of.
+ *
+ * Throwing from the wrapped `getSession` — rather than from `onStatus` — rides a documented
+ * part of `wait-for-session.js`'s own contract ("A `getSession` rejection ... propagates
+ * as-is"), instead of relying on the undocumented fact that `onStatus` happens to run outside
+ * a try/catch. `onStatus` itself is passed through untouched, still only for status-change
+ * narration (e.g. to stderr).
+ *
+ * Resolves to `{ kind: "usage_limit", session }`, `{ kind: "timeout", session }`, or
+ * `{ kind: "terminal", session }` — never rejects for a usage-limit signal; a genuine
+ * `getSession` failure (network/API error) still propagates, exactly as `waitForSession` docs.
+ */
+export async function waitForSmokeSession(
+  client,
+  sessionId,
+  { timeoutMs, intervalMs, sleep, now, onStatus },
+) {
+  try {
+    const result = await waitForSession(usageLimitWatchedClient(client), sessionId, {
+      timeoutMs,
+      intervalMs,
+      sleep,
+      now,
+      onStatus,
+    });
+    return { kind: result.timedOut ? "timeout" : "terminal", session: result.session };
+  } catch (error) {
+    if (error instanceof UsageLimitSignal) return { kind: "usage_limit", session: error.session };
+    throw error;
+  }
+}
+
+/** One-line diagnosis for a timed-out provider, keyed off the last observed status — see
+ * `host-smoke.js`'s usage text and the README for the fuller explanation. */
+export function timeoutHint(lastStatus) {
+  if (lastStatus === "queued") {
+    return (
+      "session stayed queued — check that an online host advertises a ready execution " +
+      "profile for this provider's account (HARNESS_EXECUTION_PROFILES), and that something " +
+      "is running the scheduler (POST /scheduler/assign)"
+    );
+  }
+  return `session was still ${lastStatus} when the timeout elapsed`;
+}

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

@@ -0,0 +1,172 @@
+import { AutoHarnessError } from "../../index.js";
+import { pathSegment } from "../path-segment.js";
+import { resolveSessionTarget } from "./session-target.js";
+import { step } from "./host-smoke-format.js";
+import { timeoutHint } from "./host-smoke-poll.js";
+import { runSessionAttempts } from "./host-smoke-session-attempt.js";
+
+/** Cancels a session smoke created and, either way, removes it from the shared
+ * `activeSessionIds` bookkeeping the top-level teardown uses as its safety net — unless the
+ * cancel call itself fails for a reason other than "already terminal" (409), in which case the
+ * id is deliberately left in the set so `teardownSmoke` retries it at the end of the run. */
+async function cancelForOutcome(client, io, sessionId, activeSessionIds) {
+  try {
+    await client.cancelSession(sessionId);
+    activeSessionIds.delete(sessionId);
+  } catch (error) {
+    if (error instanceof AutoHarnessError && error.status === 409) {
+      activeSessionIds.delete(sessionId); // raced to terminal on its own; nothing to cancel
+      return;
+    }
+    io.stderr.write(
+      `  session ${sessionId}: cancel failed (${error.message}); teardown will retry it\n`,
+    );
+  }
+}
+
+async function fetchStdout(client, sessionId) {
+  const page = await client.request(`/sessions/${pathSegment(sessionId, "sessionId")}/logs`);
+  return (page.items ?? [])
+    .filter((item) => item.stream === "stdout")
+    .map((item) => item.content)
+    .join("\n");
+}
+
+/**
+ * Runs one `--provider`'s end-to-end smoke session: resolve the target, then hand off to
+ * `runSessionAttempts` (create + wait, with a narrow, bounded retry for one specific
+ * "host hasn't caught up with the repo it just attached" failure — a host's cached inventory
+ * only refreshes on its own periodic poll, there is no push-on-write, and `host smoke` attaches
+ * its own throwaway repository immediately before creating a session against it, which races
+ * that poll in any real deployment, not only in a fast test), then check its logs. Always
+ * resolves to an outcome object — `{ provider, pass, ... }` — never throws or rejects, so a
+ * bad `--provider` value or a mid-poll network blip fails only *this* provider rather than
+ * aborting the ones after it; `host-smoke.js`'s loop relies on that to keep going.
+ */
+export async function runProviderSmoke({
+  client,
+  io,
+  repositoryId,
+  providerRef,
+  marker,
+  timeoutSeconds,
+  activeSessionIds,
+  sleep,
+  now,
+  intervalMs,
+}) {
+  let target;
+  try {
+    target = await resolveSessionTarget(client, { "--provider": providerRef });
+  } catch (error) {
+    step(io, false, `provider ${providerRef}: could not resolve target: ${error.message}`);
+    return {
+      provider: providerRef,
+      pass: false,
+      reason: "target_resolution_failed",
+      message: error.message,
+    };
+  }
+
+  const outcome = await runSessionAttempts({
+    client,
+    io,
+    repositoryId,
+    providerRef,
+    target,
+    marker,
+    timeoutSeconds,
+    activeSessionIds,
+    sleep,
+    now,
+    intervalMs,
+  });
+
+  if (outcome.kind === "create_failed") {
+    step(io, false, `provider ${providerRef}: create session failed: ${outcome.message}`);
+    return {
+      provider: providerRef,
+      pass: false,
+      reason: "create_failed",
+      message: outcome.message,
+    };
+  }
+  if (outcome.kind === "session_wait_failed") {
+    step(io, false, `provider ${providerRef}: session wait failed: ${outcome.message}`);
+    return {
+      provider: providerRef,
+      pass: false,
+      reason: "session_wait_failed",
+      sessionId: outcome.sessionId,
+      message: outcome.message,
+    };
+  }
+  if (outcome.kind === "usage_limit") {
+    await cancelForOutcome(client, io, outcome.sessionId, activeSessionIds);
+    const message = "provider account hit its usage limit";
+    step(io, false, `provider ${providerRef}: ${message}`);
+    return {
+      provider: providerRef,
+      pass: false,
+      reason: "usage_limit",
+      sessionId: outcome.sessionId,
+      message,
+    };
+  }
+  if (outcome.kind === "timeout") {
+    await cancelForOutcome(client, io, outcome.sessionId, activeSessionIds);
+    const hint = timeoutHint(outcome.session.status);
+    step(io, false, `provider ${providerRef}: timed out after ${timeoutSeconds}s (${hint})`);
+    return {
+      provider: providerRef,
+      pass: false,
+      reason: "timeout",
+      sessionId: outcome.sessionId,
+      message: hint,
+    };
+  }
+
+  // Terminal: already resolved on its own, nothing left for teardown to cancel.
+  const { session, sessionId } = outcome;
+  if (session.status !== "completed" || session.exitCode !== 0) {
+    const detail = session.errorMessage ?? `exitCode=${session.exitCode ?? "n/a"}`;
+    step(io, false, `provider ${providerRef}: session ${session.status} (${detail})`);
+    return {
+      provider: providerRef,
+      pass: false,
+      reason: "session_failed",
+      sessionId,
+      status: session.status,
+      exitCode: session.exitCode,
+      message: detail,
+    };
+  }
+
+  let stdout;
+  try {
+    stdout = await fetchStdout(client, sessionId);
+  } catch (error) {
+    step(io, false, `provider ${providerRef}: fetching logs failed: ${error.message}`);
+    return {
+      provider: providerRef,
+      pass: false,
+      reason: "logs_failed",
+      sessionId,
+      message: error.message,
+    };
+  }
+  if (!stdout.includes(marker)) {
+    const message = "completed but marker was not found in stdout";
+    step(io, false, `provider ${providerRef}: ${message}`);
+    return { provider: providerRef, pass: false, reason: "marker_missing", sessionId, message };
+  }
+
+  step(io, true, `provider ${providerRef}: PASS`);
+  return {
+    provider: providerRef,
+    pass: true,
+    sessionId,
+    status: session.status,
+    exitCode: session.exitCode,
+  };
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Creates a throwaway repository for `host smoke` to attach, run one prompt through, and delete
+ * again in its teardown. The daemon dispatches sessions against the host-local path this same
+ * run attaches (see `smokeInventoryEntry` below) — it never fetches or dials a repository's
+ * `url` — so a syntactically valid but inert HTTPS placeholder under the `example.test`
+ * reserved TLD (RFC 2606) is fine here, exactly like `e2e/real-cli/real-cli-helpers.ts` and
+ * `e2e/control/orchestration.spec.ts` already use for the same reason. `randomHex(bytes)` is
+ * injected (defaults to `node:crypto`'s `randomBytes` in `host-smoke.js`) so tests can assert
+ * on a deterministic generated name.
+ */
+export async function createSmokeRepository(client, randomHex) {
+  const name = `smoke-${randomHex(6)}`;
+  return client.request("/repositories", {
+    method: "POST",
+    body: JSON.stringify({
+      name,
+      url: `https://example.test/${name}.git`,
+      defaultBranch: "main",
+    }),
+  });
+}
+
+/**
+ * The inventory entry `host smoke` attaches via `attachRepository` — one worktree, named after
+ * the throwaway repository (`smoke-<hex>`), under `<repoPath>/.worktrees/<that name>`. Worktree
+ * names are one namespace across every host (`services/api/src/control-plane-worktree-names.ts`),
+ * so a fixed name would make two concurrent smokes on different hosts, or a leftover smoke
+ * worktree anywhere in the fleet, reject this attach. `repoPath` is a path on the HOST, which may be a
+ * different machine from wherever this CLI runs, so this never joins it with `node:path` (whose
+ * separator would be wrong for a remote host) or checks it exists — see `host-smoke.js`'s usage
+ * text and the README for the preconditions this command cannot verify itself: `repoPath` must
+ * already be a git repository with a clean `main` checkout, and `.worktrees/` must be gitignored
+ * there so the daemon's worktree checkout never collides with tracked files.
+ */
+export function smokeInventoryEntry(repository, repoPath) {
+  return {
+    id: repository.id,
+    path: repoPath,
+    defaultBranch: repository.defaultBranch ?? "main",
+    worktrees: [
+      {
+        id: repository.name,
+        name: repository.name,
+        path: `${repoPath}/.worktrees/${repository.name}`,
+        labels: [],
+      },
+    ],
+  };
+}

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

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

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

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