auto-harness-client 0.6.0 → 0.8.0

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

@@ -0,0 +1,87 @@
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+
+// This repo's list/history invariant forbids unbounded collection of pages at storage, so
+// `--all` stops here and warns rather than following `nextCursor` forever.
+const MAX_ALL_PAGES = 20;
+
+/** `GET /hosts`, optionally filtered by `online`/`offline` and paged with `limit`/`cursor`.
+ * `--all` follows `nextCursor` itself, capped at `MAX_ALL_PAGES` pages. */
+export async function runHostList(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--limit", "--cursor"],
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--online", "--offline", "--all", "--json"],
+  });
+  if (positionals.length > 0) {
+    throw new CliUsageError(`host list takes no arguments; received: ${positionals.join(" ")}`);
+  }
+  if (flags["--online"] && flags["--offline"]) {
+    throw new CliUsageError("--online and --offline are mutually exclusive");
+  }
+  const client = await createClient(flags, io);
+  return flags["--all"] ? runListAll(client, flags, io) : runListOnePage(client, flags, io);
+}
+
+function buildQuery(flags, cursor) {
+  const query = new URLSearchParams();
+  if (flags["--online"]) query.set("online", "online");
+  if (flags["--offline"]) query.set("online", "offline");
+  if (flags["--limit"] !== undefined) query.set("limit", flags["--limit"]);
+  if (cursor !== undefined) query.set("cursor", cursor);
+  const suffix = query.toString();
+  return suffix ? `/hosts?${suffix}` : "/hosts";
+}
+
+async function runListOnePage(client, flags, io) {
+  const page = await client.request(buildQuery(flags, flags["--cursor"]));
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify(page, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(formatHostLines(page.items ?? []));
+  if (page.nextCursor) {
+    io.stdout.write(
+      `more hosts available; pass --cursor ${page.nextCursor} to continue (or --all)\n`,
+    );
+  }
+  return 0;
+}
+
+async function runListAll(client, flags, io) {
+  const items = [];
+  const seenCursors = new Set();
+  let cursor = flags["--cursor"];
+  for (let pageCount = 0; pageCount < MAX_ALL_PAGES; pageCount += 1) {
+    const page = await client.request(buildQuery(flags, cursor));
+    items.push(...(page.items ?? []));
+    cursor = page.nextCursor || undefined;
+    if (!cursor) break;
+    // Mirrors the same guard in AutoHarnessClient#listCatalog: a server repeating a cursor is a
+    // bug worth failing loudly on, not something to paper over as "more pages than the cap".
+    if (seenCursors.has(cursor)) throw new Error("repeated pagination cursor for /hosts");
+    seenCursors.add(cursor);
+  }
+  if (cursor) {
+    io.stderr.write(
+      `warning: --all stopped after ${MAX_ALL_PAGES} pages; more hosts remain ` +
+        `(nextCursor: ${cursor})\n`,
+    );
+  }
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ items }, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(formatHostLines(items));
+  return 0;
+}
+
+function formatHostLines(items) {
+  if (items.length === 0) return "(no hosts)\n";
+  return `${items
+    .map(
+      (host) =>
+        `${host.hostId}  ${host.online ? "online" : "offline"}${host.draining ? "  draining" : ""}`,
+    )
+    .join("\n")}\n`;
+}

package/src/cli/commands/host-post-action.js

@@ -0,0 +1,38 @@
+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 { reportError } from "../report-error.js";
+
+/**
+ * Shared shape for `host drain` and `host resume`: both POST `{ hostId }` in the body — never
+ * the path, see `local-routes-host-drain.ts` — and both can 409 on a host connection race. A
+ * 409 is reported here, inside the command, rather than left to `main.js`'s catch: once that
+ * catch runs there is no way back into this function to add the trailing retry hint, so this
+ * prints the normal error line itself (via `reportError`) and then the hint, in that order.
+ * `onSuccess(result, hostId, flags)` writes the success output — it closes over its own `io`
+ * rather than taking one here, so it does not shadow this function's `io` parameter.
+ */
+export async function runHostIdPostAction(argv, io, { commandName, path, onSuccess }) {
+  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: auto-harness host ${commandName} <hostId> [--json]`);
+  }
+  const client = await createClient(flags, io);
+  let result;
+  try {
+    result = await client.request(path, { method: "POST", body: JSON.stringify({ hostId }) });
+  } catch (error) {
+    const exitCode = reportError(error, io);
+    if (error instanceof AutoHarnessError && error.status === 409) {
+      io.stderr.write("hint: the host's connection changed mid-request; retrying is safe\n");
+    }
+    return exitCode;
+  }
+  onSuccess(result, hostId, flags);
+  return 0;
+}

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

@@ -0,0 +1,51 @@
+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]";
+
+/**
+ * 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, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--dry-run", "--json"],
+  });
+  const [hostId, repositoryId] = positionals;
+  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 result = await detachRepository(client, hostId, repositoryId, {
+    dryRun: Boolean(flags["--dry-run"]),
+  });
+  printResult(io, flags, result);
+  return 0;
+}
+
+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 removed from host ${info.hostId} by ` +
+        `another writer (now at version ${info.toVersion})\n`,
+    );
+    return;
+  }
+  const verb = info.dryRun ? "would remove" : "removed";
+  const lines = [
+    `${verb} repository ${info.repository.id} (${info.repository.path}) from host ${info.hostId}`,
+  ];
+  if (info.worktreeIds.length > 0) {
+    lines.push(`  worktrees removed with it: ${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.js

@@ -0,0 +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 <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 <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-resume.js

@@ -0,0 +1,17 @@
+import { runHostIdPostAction } from "./host-post-action.js";
+
+/** `POST /hosts/resume` with `{ hostId }` in the body. Idempotent: safe on a host that is not
+ * currently draining. */
+export async function runHostResume(argv, io) {
+  return runHostIdPostAction(argv, io, {
+    commandName: "resume",
+    path: "/hosts/resume",
+    onSuccess: (result, hostId, flags) => {
+      if (flags["--json"]) {
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+      }
+      io.stdout.write(`host ${hostId} resumed (safe to run even if it was not draining)\n`);
+    },
+  });
+}

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: [],
+      },
+    ],
+  };
+}