@jr2/cli 0.1.0

package/src/cli.ts

@@ -0,0 +1,110 @@
+// Top-level dispatch (ADR-0009). `argv[0]` is the verb; the rest is handed to that command, which does
+// its own `parseArgs`. `main` returns an exit code (the bin sets `process.exitCode`) and never throws:
+// a command error becomes an `error: …` line on stderr + code 1. Codes: 0 ok, 1 runtime error, 2 usage.
+
+import { activity, defaultIo, type Io } from "./output.ts";
+import { JR2HttpError } from "./client.ts";
+import { loadDotenv } from "./env.ts";
+import { init } from "./commands/init.ts";
+import { run } from "./commands/run.ts";
+import { runs } from "./commands/runs.ts";
+import { status } from "./commands/status.ts";
+import { logs } from "./commands/logs.ts";
+import { send } from "./commands/send.ts";
+import { up } from "./commands/up.ts";
+import { down } from "./commands/down.ts";
+import { gc } from "./commands/gc.ts";
+import { kit } from "./commands/kit.ts";
+
+const USAGE = `jr2 — orchestrate agentic workflows (ADR-0009)
+
+usage: jr2 <command> [args]
+
+  init [dir] [--name <n>]            scaffold a new instance folder
+  up [--yes] [--force]              converge the current kube context to this instance (ADR-0019)
+  down [--all]                      remove the instance from the cluster (--all: operator too)
+  gc [--dry-run] [--repo-ttl 7d]    remove jr2's images that no live instance names (ADR-0039), and
+                                    Repo resources no Machine binds and no run attached lately (ADR-0051)
+  kit push <registry>               mirror the published kit images into a registry (ADR-0044)
+  run <workflow> [--input <json>]   start a run; stream activity, print terminal result
+       [--detach]                   ...or just print the runId and return
+  runs                              list live runs
+  status [runId]                    print a run's current status (read-through),
+                                    or the instance's Repos, per node, when given none (ADR-0048/0051)
+  logs <runId> [-f]                 replay a run's status; -f to follow until it settles
+  send <runId> --event CANCEL       abandon a live run
+  send <runId> --gate <gate> --event <name> [--input <json>]
+                                    deliver a workflow event to an open gate
+
+run ids: any <runId> above may be abbreviated to a unique prefix (4+ chars, git-style);
+         an ambiguous prefix lists the candidates and fails rather than guessing
+
+global (run verbs): -n/--namespace <ns>, --context <ctx> address the deployment (ADR-0019);
+                    --url <u> / JR2_URL attaches to a specific orchestrator (skips kube entirely)`;
+
+/**
+ * The catch-all half of skew reporting: a route-shaped failure gets ONE extra line naming what the
+ * instance says it is. Deliberately not a diagnosis — `run-id.ts` diagnoses the one case we can
+ * prove, and this covers the routes nobody has thought to special-case yet.
+ *
+ * Scoped to 404/405 because those are the codes a MISSING route produces; a 400/401/403/409 is the
+ * instance understanding the request and refusing it, where naming the version would be noise. And
+ * it says nothing when the instance reports no version at all, since a host-booted fixture process
+ * (the e2e tier's) legitimately has neither version nor hash to report.
+ */
+function skewNote(err: unknown): string | undefined {
+  if (!(err instanceof JR2HttpError)) return undefined;
+  if (err.status !== 404 && err.status !== 405) return undefined;
+  const { version, hash } = err.instance ?? {};
+  if (!version) return undefined;
+  const id = hash ? `${version} (${hash})` : version;
+  return `  instance: ${id} — if it predates this CLI, \`jr2 up\` converges the cluster to this kit`;
+}
+
+export async function main(argv: string[], io: Io = defaultIo): Promise<number> {
+  const [cmd, ...rest] = argv;
+  try {
+    // Before any verb, so the instance's `.env` is in `process.env` by the time a command imports
+    // `jr2.config.ts` (whose deployment-varying values are read from there — ADR-0019).
+    loadDotenv(io);
+    switch (cmd) {
+      case "init":
+        return await init(rest, io);
+      case "run":
+        return await run(rest, io);
+      case "runs":
+        return await runs(rest, io);
+      case "status":
+        return await status(rest, io);
+      case "logs":
+        return await logs(rest, io);
+      case "send":
+        return await send(rest, io);
+      case "up":
+        return await up(rest, io);
+      case "down":
+        return await down(rest, io);
+      case "gc":
+        return await gc(rest, io);
+      case "kit":
+        return await kit(rest, io);
+      case "help":
+      case "--help":
+      case "-h":
+        activity(io, USAGE);
+        return 0;
+      case undefined:
+        activity(io, USAGE);
+        return 2;
+      default:
+        activity(io, `unknown command: ${cmd}`);
+        activity(io, USAGE);
+        return 2;
+    }
+  } catch (err) {
+    activity(io, `error: ${err instanceof Error ? err.message : String(err)}`);
+    const note = skewNote(err);
+    if (note) activity(io, note);
+    return 1;
+  }
+}

package/src/client.ts

@@ -0,0 +1,219 @@
+// The shared HTTP client every `jr2` verb sits on (ADR-0009). One thin class over the orchestrator's
+// REST + SSE surface (`createApp`) — the SAME wire the deployed orchestrator serves, so `jr2` against
+// the e2e tier's host-booted fixture and against a cluster are one code path. It carries no folder/CLI concerns (those
+// live in `instance.ts`); it is just "talk to a base URL".
+//
+// `fetchImpl` is injectable so tests drive it with a hono `app.request` (no socket) the same way the
+// orchestrator's own http tests do; in production it defaults to the global `fetch`.
+
+import type { MachineDoc, RepoStatus } from "@jr2/orchestrator";
+import { parseSSE } from "./sse.ts";
+
+/** A run's current observable state — mirrors the orchestrator's `RunStatus` (run-host.ts). */
+export type RunStatus = {
+  runId: string;
+  workflow: string;
+  instanceId: string;
+  status: string;
+  value: unknown;
+  context: unknown;
+  /** Why the host set this status, for statuses the Machine did not choose — `drifted` says the
+   * workflow changed shape since the run was saved, and names both fingerprints (ADR-0030). */
+  reason?: string;
+};
+
+/** One item on a run's observation feed — mirrors the orchestrator's `RunFeedEvent`. */
+export type RunFeedEvent =
+  | { kind: "status"; status: RunStatus }
+  | { kind: "emit"; event: { type: string } & Record<string, unknown> }
+  | { kind: "retry"; child: string; attempt: number; reason: string };
+
+/** A run-control event posted to a live run (ADR-0013): CANCEL is the vocabulary that is left. */
+export type RunEvent = { type: string };
+
+/** The subset of `fetch` the client uses. `globalThis.fetch` and hono's `app.request` both satisfy it. */
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+
+const JSON_HEADERS = { "content-type": "application/json" };
+
+/** The prefix-resolution route. Named because `run-id.ts` matches on it to tell "no run by that
+ * prefix" apart from "this instance predates the route entirely" (ADR-0009). */
+export const RESOLVE_PATH = "/runs/resolve";
+
+/** What an orchestrator says it is (`GET /healthz`). Both fields are optional because an instance
+ * deployed before `/healthz` grew them answers a bare `{ ok: true }` — the absence is itself skew
+ * evidence, so it must not be an error. */
+export type InstanceIdentity = { version?: string; hash?: string };
+
+/**
+ * A non-2xx from the orchestrator, with the status code and path KEPT (ADR-0009). The bare `Error`
+ * this replaces flattened every failure to a message string, which made "unknown run" and "this
+ * instance has no such route" indistinguishable — the difference between a real 404 and version
+ * skew. Callers branch on `status`/`path`; `instance` is the best-effort identity probed at throw
+ * time, while the transport (a port-forward that the command's `finally` is about to close) is
+ * still open.
+ */
+export class JR2HttpError extends Error {
+  readonly status: number;
+  readonly path: string;
+  readonly instance?: InstanceIdentity;
+
+  constructor(message: string, status: number, path: string, instance?: InstanceIdentity) {
+    super(message);
+    this.name = "JR2HttpError";
+    this.status = status;
+    this.path = path;
+    this.instance = instance;
+  }
+}
+
+export class JR2Client {
+  readonly baseUrl: string;
+  private readonly fetchImpl: FetchLike;
+  /** The Instance token (ADR-0013). The run and gate surfaces are authenticated; without it every
+   * call below is a 401. Absent only for an unauthenticated surface (a test's in-process app). */
+  private readonly token?: string;
+
+  constructor(baseUrl: string, fetchImpl: FetchLike = globalThis.fetch, token?: string) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.fetchImpl = fetchImpl;
+    this.token = token;
+  }
+
+  /** Request headers: the bearer, plus whatever the call adds. */
+  private headers(extra: Record<string, string> = {}): Record<string, string> {
+    return this.token ? { ...extra, authorization: `Bearer ${this.token}` } : extra;
+  }
+
+  /** `GET /workflows` — names of the registered workflows. */
+  async workflows(): Promise<string[]> {
+    return (await this.json(await this.fetchImpl(`${this.baseUrl}/workflows`), "/workflows")) as string[];
+  }
+
+  /** `GET /workflows/:name/machine` — the workflow's Machine as the Console's DTO. */
+  async machine(workflow: string): Promise<MachineDoc> {
+    const res = await this.fetchImpl(`${this.baseUrl}/workflows/${encodeURIComponent(workflow)}/machine`);
+    return (await this.json(res, "/workflows/:name/machine")) as MachineDoc;
+  }
+
+  /** `POST /workflows/:name/runs` — start a run; unknown workflow → 404 → throws. */
+  async start(workflow: string, input: Record<string, unknown> = {}): Promise<{ runId: string; instanceId: string }> {
+    const res = await this.fetchImpl(`${this.baseUrl}/workflows/${encodeURIComponent(workflow)}/runs`, {
+      method: "POST",
+      headers: this.headers(JSON_HEADERS),
+      body: JSON.stringify(input),
+    });
+    return (await this.json(res, "/workflows/:name/runs")) as { runId: string; instanceId: string };
+  }
+
+  /** `GET /runs` — every live run's status. */
+  async list(): Promise<RunStatus[]> {
+    const res = await this.fetchImpl(`${this.baseUrl}/runs`, { headers: this.headers() });
+    return (await this.json(res, "/runs")) as RunStatus[];
+  }
+
+  /** `GET /repos` — whether the instance has a data plane, and every Repo resource as the cluster
+   * reports it (ADR-0048/0051): per node, present or not, synced or not, with git's own error. The
+   * cache agent keeps retrying on its own, so this is a snapshot of a moving thing. What
+   * `jr2 status` reports when it is given no run. */
+  async repos(): Promise<{ dataPlane: boolean; repos: RepoStatus[] }> {
+    const res = await this.fetchImpl(`${this.baseUrl}/repos`, { headers: this.headers() });
+    return (await this.json(res, "/repos")) as { dataPlane: boolean; repos: RepoStatus[] };
+  }
+
+  /** `GET /runs/resolve?prefix=` — run ids sharing a prefix, live and settled. The wire half of
+   * abbreviated run ids; the policy (floor, uuid fast path, ambiguity) lives in `run-id.ts`. */
+  async candidates(prefix: string): Promise<{ runIds: string[]; truncated: boolean }> {
+    const res = await this.fetchImpl(`${this.baseUrl}/runs/resolve?prefix=${encodeURIComponent(prefix)}`, {
+      headers: this.headers(),
+    });
+    const body = (await this.json(res, RESOLVE_PATH)) as { runIds: string[]; truncated: boolean };
+    return { runIds: body.runIds, truncated: body.truncated };
+  }
+
+  /** `GET /runs/:runId` (read-through) — terminal runs included; a genuinely unknown run → undefined. */
+  async read(runId: string): Promise<RunStatus | undefined> {
+    const res = await this.fetchImpl(`${this.baseUrl}/runs/${encodeURIComponent(runId)}`, {
+      headers: this.headers(),
+    });
+    if (res.status === 404) return undefined;
+    return (await this.json(res, "/runs/:runId")) as RunStatus;
+  }
+
+  /** `POST /runs/:runId/gates/:gate/events` — deliver a workflow-defined event to an open gate
+   * (ADR-0011). The body is `{ type, ...input }`, validated against the event's schema host-side;
+   * an unknown gate (404) or rejected payload (400) surfaces as a throw. */
+  async sendToGate(runId: string, gate: string, event: { type: string } & Record<string, unknown>): Promise<void> {
+    const res = await this.fetchImpl(
+      `${this.baseUrl}/runs/${encodeURIComponent(runId)}/gates/${encodeURIComponent(gate)}/events`,
+      { method: "POST", headers: this.headers(JSON_HEADERS), body: JSON.stringify(event) },
+    );
+    await this.json(res, "/runs/:runId/gates/:gate/events"); // surface { error }; ignore { ok:true }
+  }
+
+  /** `POST /runs/:runId/events` — feed one run-control event into a live run. */
+  async send(runId: string, event: RunEvent): Promise<void> {
+    const res = await this.fetchImpl(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/events`, {
+      method: "POST",
+      headers: this.headers(JSON_HEADERS),
+      body: JSON.stringify(event),
+    });
+    await this.json(res, "/runs/:runId/events"); // surface { error }; ignore { ok:true }
+  }
+
+  /**
+   * `GET /runs/:runId/events` — the SSE feed as an async-iterable of `RunFeedEvent`. The current status
+   * is replayed first (attach), then deltas + author `emit`s until the terminal status (or the consumer
+   * breaks, which cancels the stream). A settled run streams its final status once and ends.
+   */
+  async *events(runId: string): AsyncGenerator<RunFeedEvent> {
+    const res = await this.fetchImpl(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/events`, {
+      headers: this.headers({ accept: "text/event-stream" }),
+    });
+    if (res.status === 404) {
+      throw new JR2HttpError(`no run "${runId}"`, 404, "/runs/:runId/events", await this.identify());
+    }
+    if (!res.body) return;
+    for await (const frame of parseSSE(res.body)) {
+      if (frame.event === "emit") {
+        yield { kind: "emit", event: JSON.parse(frame.data) as { type: string } & Record<string, unknown> };
+      } else if (frame.event === "retry") {
+        yield { kind: "retry", ...(JSON.parse(frame.data) as { child: string; attempt: number; reason: string }) };
+      } else if (frame.event === "status") {
+        yield { kind: "status", status: JSON.parse(frame.data) as RunStatus };
+      }
+      // Any other frame (a Turn marker — ADR-0023 — or a kind this CLI predates) is skipped, not
+      // misread as a status: `jr2 logs -f` decides "settled" off `status.status`, and a marker
+      // parsed as a status would end the follow mid-run.
+    }
+  }
+
+  /**
+   * `GET /healthz` — what this orchestrator says it is. Unauthenticated (it is the readiness probe),
+   * best-effort by contract: an unreachable or older instance answers `undefined`/`{}` rather than
+   * throwing, because this is only ever called to EXPLAIN another failure and must never replace it.
+   */
+  async identify(): Promise<InstanceIdentity | undefined> {
+    try {
+      const res = await this.fetchImpl(`${this.baseUrl}/healthz`);
+      if (!res.ok) return undefined;
+      const body = (await res.json()) as InstanceIdentity;
+      return { version: body.version, hash: body.hash };
+    } catch {
+      return undefined; // the probe is a courtesy; its failure is not the user's error
+    }
+  }
+
+  /** Parse a JSON response, turning a non-2xx `{ error }` body into a thrown `JR2HttpError`. */
+  private async json(res: Response, path: string): Promise<unknown> {
+    const text = await res.text();
+    const body = text ? JSON.parse(text) : undefined;
+    if (!res.ok) {
+      const message = (body as { error?: string } | undefined)?.error ?? `HTTP ${res.status}`;
+      // Probe HERE, not at the catch site: by the time the error reaches `cli.ts` the command's
+      // `finally` has closed the port-forward, and there is nothing left to ask.
+      throw new JR2HttpError(message, res.status, path, await this.identify());
+    }
+    return body;
+  }
+}

package/src/commands/down.ts

@@ -0,0 +1,104 @@
+// `jr2 down [--all] [-n <ns>] [--context <ctx>]` (ADR-0019): remove the instance from the cluster —
+// its namespace and everything `jr2 up` converged into it. ALWAYS confirms (deleting a namespace
+// takes the runs, the store PVC, and every live Sandbox with it). `--all` also uninstalls the
+// per-cluster operator — only sane when this was the cluster's last instance, which is the
+// caller's judgment, not derivable here.
+//
+// It also sweeps IMAGES — on the host daemon that built them and, on kind, on every node (ADR-0039).
+// Content addressing means ten Dockerfile iterations leave ten full images per store — invisible to
+// `kubectl`, on the developer's own disk, and discovered at 100% full rather than at the moment
+// anyone would think to pass a flag. Hence: by default, not behind a flag.
+//
+// The MECHANISM is the delete that just happened, not a name match: with this instance's namespace
+// gone, its image map, its Sandboxes, and its pods are gone with it, so its images are unreachable
+// by construction — while every other instance's roots still protect everything they share, kit
+// refs included. Nothing here parses a tag.
+//
+// What the namespace delete does NOT reclaim: the node cache directories under
+// `/var/lib/jr2/<namespace>/repos` (ADR-0051). The cache agent evicts a Repo's copy on its resource's
+// deletion, but the DaemonSet dies with the namespace before it can act on the Repos going with it,
+// so the bare clones stay on each node. They are inert — nothing mounts or refreshes them — and
+// bounded by the node's disk; on kind they live inside the node container and go with the cluster.
+
+import { basename } from "node:path";
+import { parseArgs } from "node:util";
+import { loadConfig } from "@jr2/orchestrator";
+import { pnpmDockerBuild } from "../build.ts";
+import { KIT_VERSION, LABEL_INSTANCE, operatorManifest } from "../deploy.ts";
+import { resolveRoot } from "../instance.ts";
+import { kubectlAdmin } from "../kube.ts";
+import { activity, confirmOrBail, type Io } from "../output.ts";
+import { sweepImages } from "../sweep.ts";
+
+export async function down(args: string[], io: Io): Promise<number> {
+  const { values } = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      all: { type: "boolean" },
+      yes: { type: "boolean" },
+      namespace: { type: "string", short: "n" },
+      context: { type: "string" },
+    },
+  });
+
+  const root = resolveRoot(io.cwd);
+  const config = (await loadConfig(root)) ?? {};
+  const name = config.name ?? basename(root);
+  const namespace = (values.namespace as string | undefined) ?? name;
+  const kube = io.kubeAdmin ?? kubectlAdmin;
+  const context = (values.context as string | undefined) ?? (await kube.context());
+  if (!context) throw new Error("no kube context — nothing to remove from");
+  const ctx = values.context ? { context: values.context as string } : {};
+
+  const ns = await kube.getJson({ kind: "namespace", name: namespace, ...ctx });
+  const owner = ns?.metadata.labels?.[LABEL_INSTANCE];
+  if (!ns || !owner) {
+    activity(io, `not deployed here — namespace "${namespace}" on ${context} holds no jr2 instance`);
+    return 1;
+  }
+  if (owner !== name) {
+    activity(io, `refusing: namespace "${namespace}" on ${context} belongs to another instance ("${owner}")`);
+    return 1;
+  }
+
+  const scope = values.all ? " AND the per-cluster operator" : "";
+  const ok =
+    values.yes === true ||
+    (await confirmOrBail(
+      io,
+      `remove instance "${name}" from context ${context} (delete namespace "${namespace}"${scope})?`,
+    ));
+  if (!ok) {
+    activity(io, "aborted — nothing was changed");
+    return 1;
+  }
+
+  activity(io, `deleting namespace "${namespace}" (runs, store, and Sandboxes go with it)`);
+  await kube.deleteObject({ kind: "Namespace", name: namespace, ...ctx });
+
+  // BEFORE the sweep, not after: while the operator Deployment stands, its pod is a live root and
+  // the operator image would survive its own uninstall.
+  if (values.all) {
+    activity(io, "uninstalling the operator (jr2-system)");
+    // The image ref doesn't matter for a delete-by-manifest; the object names do.
+    await kube.deleteManifest({ manifest: await operatorManifest(`jr2-operator:${KIT_VERSION}`), ...ctx });
+  }
+
+  // AFTER both deletes, which is the whole mechanism (see the module doc): `deleteObject` waits, so
+  // this instance's roots are gone before the roots read runs. No grace — a namespace that no
+  // longer exists has no propagation window to lose a provision in. `kubectl delete -f` waits on
+  // the operator Deployment but not on its pods, so a terminating operator pod can still hold its
+  // image one more round; the next `jr2 gc` collects it, and excluding terminating pods instead
+  // would let a sweep take an image out from under a mid-roll one.
+  try {
+    await sweepImages({ io, build: io.build ?? pnpmDockerBuild, kube, context, ctx });
+  } catch (err) {
+    // A warning, never a non-zero exit: the instance IS removed, which is what `down` promised.
+    activity(io, `image sweep failed (${err instanceof Error ? err.message : err}) — the instance is still removed`);
+  }
+
+  activity(io, "removed");
+  return 0;
+}

package/src/commands/gc.ts

@@ -0,0 +1,73 @@
+// `jr2 gc [--dry-run] [--repo-ttl <ttl>] [--context <ctx>]` (ADR-0039, ADR-0051): the two
+// reachability sweeps, run off-cycle. An escape hatch for "disk is full now", not a step in any
+// workflow — `jr2 up` and `jr2 down` already sweep images at the two moments the root set moves, and
+// this is the same sweep with no converge attached, plus the one sweep only this verb runs: Repo
+// resources no registered Machine binds and no run has attached within `--repo-ttl` (default 7d),
+// whose deletion is what lets each node's cache agent evict its copy.
+//
+// It never confirms. By construction it removes only images jr2 built (the `jr2.dev/kind` stamp is
+// the ownership gate) and only those no live root names, and only Repo resources the Orchestrator's
+// own labels and clocks say nothing wants, so there is nothing for a human to weigh: the question
+// "is this needed?" is answered by the cluster, not by the operator of the CLI.
+//
+// It takes no `-n`. The keep set is cluster-wide by definition — a ref another instance's image map
+// or pod names is not garbage — so a namespace flag would narrow nothing and mean nothing. And it
+// resolves no instance folder: "disk is full now" has to work from anywhere, and a kube context is
+// the only address this command needs.
+
+import { parseArgs } from "node:util";
+import { pnpmDockerBuild } from "../build.ts";
+import { kubectlAdmin } from "../kube.ts";
+import { activity, type Io } from "../output.ts";
+import { DEFAULT_REPO_TTL, parseRepoTtl, sweepRepos } from "../repo-sweep.ts";
+import { sweepImages } from "../sweep.ts";
+
+export async function gc(args: string[], io: Io): Promise<number> {
+  const { values } = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      "dry-run": { type: "boolean" },
+      "repo-ttl": { type: "string" },
+      context: { type: "string" },
+    },
+  });
+  const ttl = (values["repo-ttl"] as string | undefined) ?? DEFAULT_REPO_TTL;
+  // Refused before anything is read: a TTL that does not parse must not become "sweep now".
+  parseRepoTtl(ttl);
+
+  const kube = io.kubeAdmin ?? kubectlAdmin;
+  const context = (values.context as string | undefined) ?? (await kube.context());
+  if (!context) {
+    throw new Error("no kube context — `jr2 gc` decides what is garbage by asking a cluster what it still needs");
+  }
+  const ctx = values.context ? { context: values.context as string } : {};
+  const dryRun = values["dry-run"] === true;
+
+  activity(
+    io,
+    `jr2 gc — images on ${context} that no live root names${dryRun ? " (dry run: nothing is removed)" : ""}`,
+  );
+  try {
+    await sweepImages({ io, build: io.build ?? pnpmDockerBuild, kube, context, ctx, dryRun });
+  } catch (err) {
+    // Fail closed and say so: a keep set assembled from a partial roots read is not a smaller one,
+    // it is a wrong one, and acting on it would delete another instance's images. Unlike `up` and
+    // `down` — where the sweep is a courtesy on top of a job that already succeeded — the sweep IS
+    // this command, so a sweep that took nothing is a failed run.
+    activity(io, `error: the roots could not be read (${err instanceof Error ? err.message : err})`);
+    activity(io, "  nothing was swept — a keep set missing one root would delete images the cluster still needs");
+    return 1;
+  }
+  try {
+    await sweepRepos({ io, kube, ctx, ttl, dryRun });
+  } catch (err) {
+    // A short read under-collects and nothing more — but "swept nothing" has to be the truth, not a
+    // partial list narrated as the whole, and a verb that promised a sweep and could not look is a
+    // failed run.
+    activity(io, `error: the Repo resources could not be read (${err instanceof Error ? err.message : err})`);
+    return 1;
+  }
+  return 0;
+}