@jr2/cli 0.1.0

package/src/nodes.ts

@@ -0,0 +1,74 @@
+// Which nodes are an Instance's Sandbox nodes (ADR-0052), read off the cluster's nodes with the
+// scheduler's own rules: not cordoned, every label of `sandbox.nodeSelector` present, and every
+// NoSchedule/NoExecute taint tolerated by `sandbox.tolerations`. No jr2 label exists — taints and
+// cordons already say "not for ordinary work" for every workload, and jr2 reads them instead of
+// asking for a second, jr2-only opt-in. The predicate is pure and mirrors what the Sandbox pod and
+// the cache agent's DaemonSet carry, so the set `jr2 up` reports is the set the scheduler will use —
+// at the moment of the read. The set moves (a pool autoscales, a node is cordoned), which is why an
+// empty set is reported and never refused.
+
+import type { SandboxPlacement, Toleration } from "@jr2/orchestrator";
+
+/** A cluster node, read for the facts that decide placement and platform (ADR-0045/0052). */
+export type NodeObject = {
+  metadata: { name: string; labels?: Record<string, string> };
+  spec?: { unschedulable?: boolean; taints?: readonly Taint[] };
+  status?: { nodeInfo?: { architecture?: string } };
+};
+
+export type Taint = { key: string; value?: string; effect: string };
+
+/** One node's exclusion, in the words a human acts on: the taint or label that kept it out. */
+export type Excluded = { name: string; reason: string };
+
+export type SandboxNodes = { nodes: NodeObject[]; excluded: Excluded[] };
+
+/** The Sandbox nodes among `nodes`, and why each other one is not. */
+export function sandboxNodes(nodes: readonly NodeObject[], placement: SandboxPlacement | undefined): SandboxNodes {
+  const out: SandboxNodes = { nodes: [], excluded: [] };
+  for (const node of nodes) {
+    const reason = excludedBecause(node, placement);
+    if (reason === undefined) out.nodes.push(node);
+    else out.excluded.push({ name: node.metadata.name, reason });
+  }
+  return out;
+}
+
+/**
+ * The nodes the build set is derived from (ADR-0045 as rewritten by ADR-0052): the union of the
+ * nodes an ordinary pod lands on — the Orchestrator Deployment's own placement, no selector, no
+ * tolerations — and the Sandbox nodes. A tainted pool no Sandbox reaches is never built for.
+ */
+export function buildNodes(nodes: readonly NodeObject[], placement: SandboxPlacement | undefined): NodeObject[] {
+  return nodes.filter(
+    (n) => excludedBecause(n, undefined) === undefined || excludedBecause(n, placement) === undefined,
+  );
+}
+
+/** Why `node` is not a Sandbox node under `placement`, or undefined when it is. */
+export function excludedBecause(node: NodeObject, placement: SandboxPlacement | undefined): string | undefined {
+  if (node.spec?.unschedulable === true) return "cordoned (spec.unschedulable)";
+  for (const [key, value] of Object.entries(placement?.nodeSelector ?? {})) {
+    const has = node.metadata.labels?.[key];
+    if (has !== value)
+      return has === undefined
+        ? `lacks the label ${key} that sandbox.nodeSelector requires`
+        : `label ${key}=${has} is not the ${key}=${value} that sandbox.nodeSelector requires`;
+  }
+  for (const taint of node.spec?.taints ?? []) {
+    if (taint.effect === "PreferNoSchedule") continue;
+    if (!(placement?.tolerations ?? []).some((t) => tolerates(t, taint)))
+      return `taint ${taint.key}${taint.value !== undefined && taint.value !== "" ? `=${taint.value}` : ""}:${taint.effect} is not tolerated by sandbox.tolerations`;
+  }
+  return undefined;
+}
+
+/** Kubernetes' own rule: an empty key with `Exists` matches every taint; an absent effect matches
+ * every effect; `Equal` (the default) also compares the value. */
+export function tolerates(t: Toleration, taint: Taint): boolean {
+  if (t.effect !== undefined && t.effect !== taint.effect) return false;
+  if (t.key === undefined || t.key === "") return t.operator === "Exists";
+  if (t.key !== taint.key) return false;
+  if (t.operator === "Exists") return true;
+  return (t.value ?? "") === (taint.value ?? "");
+}

package/src/output.ts

@@ -0,0 +1,211 @@
+// IO seam + output discipline (ADR-0009). The CLI keeps two streams strictly separated:
+//   - STDOUT carries the one machine-readable RESULT (terminal RunStatus, a run list, a runId) as JSON,
+//     so `jr2 run ping | jq` and friends get clean data;
+//   - STDERR carries human ACTIVITY (status deltas, author emits, notices, errors).
+// Every command takes an `Io` rather than touching `process` directly, so dispatch + commands are
+// unit-testable: tests pass buffers for out/err, a fixed cwd/env, and (optionally) a `fetch` bound to a
+// hono app so the whole client path runs without a socket.
+
+import type { BuildPort } from "./build.ts";
+import type { FetchLike } from "./client.ts";
+import type { KubeAdmin, KubePort } from "./kube.ts";
+import type { TypecheckPort } from "./typecheck.ts";
+
+export type Io = {
+  stdout: (s: string) => void;
+  stderr: (s: string) => void;
+  env: Record<string, string | undefined>;
+  cwd: string;
+  /** Override the HTTP transport (tests bind it to `app.request`); default → global `fetch`. */
+  fetch?: FetchLike;
+  /** Override the kube transport (tests inject a fake); default → `kubectl` subprocesses. */
+  kube?: KubePort;
+  /** Override the kube admin surface `jr2 up`/`down` converge through; default → `kubectl`. */
+  kubeAdmin?: KubeAdmin;
+  /** Override the image build port; default → pnpm + docker + kind subprocesses. */
+  build?: BuildPort;
+  /** Override `jr2 up`'s Instance typecheck (ADR-0050); default → the Instance's own `tsc`. */
+  typecheck?: TypecheckPort;
+  /** Where kit-checkout detection starts walking up from (ADR-0038); default → the CLI's own
+   * module directory, which is the whole signal: a checkout resolves the kit sources, an npm
+   * install does not. Exists so tests can drive both worlds instead of detecting the real repo
+   * they happen to run inside. NOT user-facing — no flag and no env reads it. */
+  kitDir?: string;
+  /** Answer a yes/no confirmation; default → interactive TTY prompt (non-TTY answers no). */
+  confirm?: (question: string) => Promise<boolean>;
+  /** Pick one of several offered options (`jr2 up`'s git-ssh key source, ADR-0047); default →
+   * an interactive TTY menu. Returns the chosen index; `undefined` is "none of these", which
+   * every caller must treat as a decline — a non-TTY always answers that. */
+  choose?: (question: string, options: string[]) => Promise<number | undefined>;
+  /** Read one VISIBLE line — a path, or the bare enter that ends a pause; default → TTY readline
+   * (non-TTY reads nothing, never hangs). */
+  prompt?: (question: string) => Promise<string>;
+  /** Read key material with echo OFF; default → TTY readline with its own echo suppressed. */
+  readSecret?: (question: string) => Promise<string>;
+  /** Override deploy-keypair generation (`jr2 up`'s ssh offer); default → `ssh-keygen`. */
+  sshKeygen?: () => Promise<{ privateKey: string; publicKey: string }>;
+  /** Derive `key.pub` from a private key the USER supplied, refusing a passphrase-protected one
+   * by name (ADR-0047); default → `ssh-keygen -y -P ""`. */
+  sshPublicKey?: (privateKey: string) => Promise<string>;
+};
+
+/** The real-process IO the `jr2` bin runs with. */
+export const defaultIo: Io = {
+  stdout: (s) => void process.stdout.write(s),
+  stderr: (s) => void process.stderr.write(s),
+  env: process.env,
+  cwd: process.cwd(),
+};
+
+/** Emit the command's machine-readable result as a JSON line on stdout. */
+export function result(io: Io, value: unknown): void {
+  io.stdout(`${JSON.stringify(value)}\n`);
+}
+
+/** Emit a human-facing activity/notice line on stderr. */
+export function activity(io: Io, line: string): void {
+  io.stderr(`${line}\n`);
+}
+
+/**
+ * Ask a yes/no question on the terminal (ADR-0019: `up` prompts exactly when meeting a cluster
+ * that isn't yet home; `down` always). Injectable via `io.confirm`; the default reads one line
+ * from the tty — and a NON-tty (CI without `--yes`) answers no, never hangs.
+ */
+export async function confirmOrBail(io: Io, question: string): Promise<boolean> {
+  if (io.confirm) return io.confirm(question);
+  if (!process.stdin.isTTY) {
+    activity(io, `${question} — not a tty; pass --yes to proceed non-interactively`);
+    return false;
+  }
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    // readline OWNS the line: pre-writing the prompt to stderr gets erased by its first
+    // line-refresh on a tty, leaving a question-less cursor that reads as a hang.
+    const answer = await rl.question(`${question} [y/N] `);
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Ask which of several offered options to take (ADR-0047: the git-ssh key source). The same
+ * discipline as `confirmOrBail` — injectable, and a non-tty answers "none" rather than hanging.
+ * Interactively it is an arrow-key menu: the highlight moves, ENTER commits it, and everything
+ * else that resolves (esc, q, ctrl-c) is "none". No keystroke but enter can pick, because this
+ * menu's entries are not interchangeable — the dangerous ones sit beside the recommended one, so
+ * a stray key must never resolve into a pick, and the caller's decline path (bail with the manual
+ * instructions) is the safe answer to an unreadable one.
+ */
+export async function chooseOrBail(io: Io, question: string, options: string[]): Promise<number | undefined> {
+  if (io.choose) return io.choose(question, options);
+  if (!process.stdin.isTTY) {
+    activity(io, `${question} — not a tty; pass --yes to take the recommended option non-interactively`);
+    return undefined;
+  }
+  return menu(question, options);
+}
+
+/** The menu's own drawing and key handling. It writes to stderr directly rather than through
+ * `activity`, because cursor moves and highlights are not activity lines — the block is redrawn
+ * in place and then collapsed to the one line worth keeping in the scrollback. */
+async function menu(question: string, options: string[]): Promise<number | undefined> {
+  const input = process.stdin;
+  const out = process.stderr;
+  const color = !process.env.NO_COLOR;
+  const { emitKeypressEvents } = await import("node:readline");
+  emitKeypressEvents(input);
+  const wasRaw = input.isRaw === true;
+  input.setRawMode(true);
+  input.resume();
+  out.write(`${question}\n\u001b[?25l`); // question stays; cursor hidden while the block moves
+
+  let cursor = 0;
+  let drawn = false;
+  const hint = "  (↑/↓ move · enter selects · esc cancels)";
+  const draw = (): void => {
+    if (drawn) out.write(`\u001b[${options.length + 1}A`); // back to the block's first line
+    for (const [i, option] of options.entries()) {
+      const line = clip(i === cursor ? `❯ ${option}` : `  ${option}`, out.columns);
+      out.write(`\u001b[2K${color && i === cursor ? `\u001b[36m${line}\u001b[0m` : line}\n`);
+    }
+    out.write(`\u001b[2K${clip(hint, out.columns)}\n`);
+    drawn = true;
+  };
+
+  return new Promise<number | undefined>((resolve) => {
+    const finish = (pick: number | undefined): void => {
+      input.off("keypress", onKey);
+      if (!wasRaw) input.setRawMode(false);
+      input.pause();
+      // Collapse the block to its outcome: a menu that scrolled past should still say what was
+      // chosen, and a redrawn one must not leave N stale lines behind.
+      out.write(`\u001b[${options.length + 1}A\u001b[0J`);
+      out.write(`${pick === undefined ? "  (cancelled)" : clip(`  ❯ ${options[pick]}`, out.columns)}\n\u001b[?25h`);
+      resolve(pick);
+    };
+    const onKey = (str: string | undefined, key: { name?: string; ctrl?: boolean } | undefined): void => {
+      if (!key) return;
+      if (key.ctrl && (key.name === "c" || key.name === "d")) return finish(undefined);
+      if (key.name === "up" || key.name === "k") cursor = (cursor + options.length - 1) % options.length;
+      else if (key.name === "down" || key.name === "j") cursor = (cursor + 1) % options.length;
+      else if (str !== undefined && /^[1-9]$/.test(str) && Number(str) <= options.length) cursor = Number(str) - 1;
+      else if (key.name === "return" || key.name === "enter") return finish(cursor);
+      else if (key.name === "escape" || key.name === "q") return finish(undefined);
+      else return; // an unmapped key changes nothing — no redraw, no pick
+      draw();
+    };
+    input.on("keypress", onKey);
+    draw();
+  });
+}
+
+/** One rendered menu line, kept to one terminal row: a wrapped line would break the cursor
+ * arithmetic the redraw depends on. A width of 0 is a terminal that never reported one (a pty
+ * opened without a size), not a zero-wide screen — assume 80 rather than clip every line away. */
+function clip(line: string, columns: number | undefined): string {
+  const width = (columns && columns > 0 ? columns : 80) - 1;
+  return line.length <= width ? line : `${line.slice(0, Math.max(1, width - 1))}…`;
+}
+
+/** Read one visible line — a path to type, or the bare enter that ends a pause. A non-tty reads
+ * nothing and returns "", so a scripted run never blocks on a human. */
+export async function promptLine(io: Io, question: string): Promise<string> {
+  if (io.prompt) return io.prompt(question);
+  if (!process.stdin.isTTY) return "";
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Read pasted key material with the terminal's echo OFF (ADR-0047) — a private key must not land
+ * in the scrollback or the shell's history of whoever is watching the screen. Multi-line by
+ * nature: lines are collected until the key's own `-----END …-----` trailer (or EOF, ctrl-D).
+ * Echo suppression is readline's own writer, silenced — which is also why the prompt may be
+ * written before the interface exists: with nothing echoed, nothing refreshes over it.
+ */
+export async function readSecretInput(io: Io, question: string): Promise<string> {
+  if (io.readSecret) return io.readSecret(question);
+  if (!process.stdin.isTTY) return "";
+  activity(io, question);
+  const { createInterface } = await import("node:readline");
+  const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+  (rl as unknown as { _writeToOutput: (s: string) => void })._writeToOutput = () => {};
+  const lines: string[] = [];
+  try {
+    for await (const line of rl) {
+      lines.push(line);
+      if (/-----END [A-Z0-9 ]*PRIVATE KEY-----/.test(line)) break;
+    }
+  } finally {
+    rl.close();
+  }
+  return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+}

package/src/repo-sweep.ts

@@ -0,0 +1,134 @@
+// The Repo half of `jr2 gc` (ADR-0051): eviction is reachability plus age. A `Repo` resource is kept
+// while a registered Machine binds it — the Orchestrator labels those at every boot and unlabels
+// what its walk no longer names — and, unbound, while a run has attached it within the TTL; the
+// Orchestrator moves that clock on every attach. What is left is a Repo nothing binds that no run
+// has asked for lately, and deleting the resource is what lets the cache agent evict the node
+// copies once nothing there mounts them. The sweep only ever deletes RESOURCES: the bytes on each
+// node are the agent's to reclaim, on its own schedule.
+//
+// Cluster-wide like the image sweep (sweep.ts): every namespace some instance owns is read, so
+// "disk is full now" reaches every instance's caches from anywhere. A cluster with no Repo CRD holds
+// no Repos — the one read that may answer "none" — while any other failure throws and the caller
+// sweeps nothing.
+
+import { ANNOTATION_REPO_LAST_ATTACHED, LABEL_REPO_BOUND } from "@jr2/orchestrator";
+import { LABEL_INSTANCE } from "./deploy.ts";
+import { isMissingResourceType, type KubeAdmin } from "./kube.ts";
+import { activity, type Io } from "./output.ts";
+
+/** The CRD, fully qualified so the read cannot collide with another `repos` resource. */
+export const REPO_KIND = "repos.core.jr2.dev";
+
+/** The eviction TTL `jr2 gc` applies when none is given. */
+export const DEFAULT_REPO_TTL = "7d";
+
+const UNIT_MS: Record<string, number> = { d: 86_400_000, h: 3_600_000, m: 60_000 };
+
+/** `<n>d|h|m` → milliseconds; `0` is "now" (evict everything unbound). Anything else is refused by
+ * name, so a typo cannot read as a zero TTL. */
+export function parseRepoTtl(text: string): number {
+  if (text === "0") return 0;
+  const m = /^(\d+)([dhm])$/.exec(text);
+  if (!m) throw new Error(`--repo-ttl ${JSON.stringify(text)} is not a TTL — use <n>d, <n>h, or <n>m (or 0 for now)`);
+  return Number(m[1]) * UNIT_MS[m[2]!]!;
+}
+
+type RepoObject = {
+  metadata: {
+    name: string;
+    namespace?: string;
+    creationTimestamp?: string;
+    labels?: Record<string, string>;
+    annotations?: Record<string, string>;
+  };
+  spec?: { url?: string };
+};
+
+/** One Repo the sweep decided about: where it is, what it clones, and when it was last wanted. */
+export type SweptRepo = { namespace: string; key: string; url: string; lastAttached: string };
+
+/**
+ * Whether one Repo is garbage at `now`, under `ttlMs`: unbound, and last attached (or, never
+ * attached, created) before the TTL's edge. An unreadable clock keeps the Repo — a resource this
+ * cannot date is not one it may take.
+ */
+export function repoIsEvictable(repo: RepoObject, now: Date, ttlMs: number): boolean {
+  if (repo.metadata.labels?.[LABEL_REPO_BOUND] === "true") return false;
+  const stamp = repo.metadata.annotations?.[ANNOTATION_REPO_LAST_ATTACHED] ?? repo.metadata.creationTimestamp;
+  if (stamp === undefined) return false;
+  const at = Date.parse(stamp);
+  if (Number.isNaN(at)) return false;
+  return now.getTime() - at >= ttlMs;
+}
+
+/**
+ * One sweep: every instance namespace's Repos, those the rule above evicts deleted (or, dry, named).
+ * Returns what went, for the caller's narration. Throws on any read the fail-closed rule does not
+ * excuse — though here a partial read can only UNDER-collect, the caller still owes the user a true
+ * "swept nothing" rather than a silent short list.
+ */
+export async function sweepRepos(opts: {
+  io: Io;
+  kube: KubeAdmin;
+  ctx: { context?: string };
+  ttl: string;
+  dryRun?: boolean;
+  now?: () => Date;
+}): Promise<SweptRepo[]> {
+  const { io, kube, ctx, ttl, dryRun } = opts;
+  const ttlMs = parseRepoTtl(ttl);
+  const now = (opts.now ?? (() => new Date()))();
+  const namespaces = (await kube.listJson({ kind: "namespace", selector: LABEL_INSTANCE, ...ctx })).map(
+    (n) => n.metadata.name,
+  );
+  const swept: SweptRepo[] = [];
+  for (const namespace of namespaces) {
+    for (const repo of await listRepos(kube, namespace, ctx)) {
+      if (!repoIsEvictable(repo, now, ttlMs)) continue;
+      const entry: SweptRepo = {
+        namespace,
+        key: repo.metadata.name,
+        url: repo.spec?.url ?? "",
+        lastAttached:
+          repo.metadata.annotations?.[ANNOTATION_REPO_LAST_ATTACHED] ?? repo.metadata.creationTimestamp ?? "",
+      };
+      if (!dryRun) await kube.deleteObject({ kind: REPO_KIND, name: entry.key, namespace, ...ctx });
+      swept.push(entry);
+    }
+  }
+  narrateRepoSweep(io, swept, { ttl, dryRun });
+  return swept;
+}
+
+/** The Repos of one namespace, with the one degradation the fail-closed rule allows: a cluster with
+ * no `repos.core.jr2.dev` resource type (the operator never reached it, or `jr2 down --all` took the
+ * CRD) holds no Repos, so "none" is the complete answer. */
+async function listRepos(kube: KubeAdmin, namespace: string, ctx: { context?: string }): Promise<RepoObject[]> {
+  try {
+    return await kube.listJson<RepoObject>({ kind: REPO_KIND, namespace, ...ctx });
+  } catch (err) {
+    if (isMissingResourceType(err)) return [];
+    throw err;
+  }
+}
+
+/** `repos: swept 2 Repo resource(s) no Machine binds and no run attached within 7d` — the count and
+ * the rule, since the rule is the whole justification; the resources themselves are listed only for
+ * a dry run, where the plan IS the output. */
+function narrateRepoSweep(io: Io, swept: SweptRepo[], opts: { ttl: string; dryRun?: boolean }): void {
+  const verb = opts.dryRun ? "would sweep" : "swept";
+  if (swept.length === 0) {
+    activity(
+      io,
+      `repos: ${verb} nothing — every Repo resource is bound by a Machine or was attached within ${opts.ttl}`,
+    );
+    return;
+  }
+  activity(
+    io,
+    `repos: ${verb} ${swept.length} Repo resource(s) no Machine binds and no run attached within ${opts.ttl}`,
+  );
+  if (opts.dryRun) {
+    for (const r of swept) activity(io, `  ${r.namespace}/${r.key} (${r.url}) — last attached ${r.lastAttached}`);
+  }
+}

package/src/run-id.ts

@@ -0,0 +1,85 @@
+// Abbreviated run ids (ADR-0009): the CLI's answer to "which run", the way `instance.ts` answers
+// "which instance". A run id is a bare uuid, so pasting all 36 characters is the common case worth
+// removing — git's short hashes, with git's rule: prefix only, and an ambiguous prefix FAILS rather
+// than guessing.
+//
+// Resolution lives here and not on the orchestrator's addressed routes. A prefix is not an identity
+// — one that resolves today goes ambiguous tomorrow when an unrelated run starts — and `jr2 send
+// <prefix> --event CANCEL` is a write. Resolving first means every write on the wire carries a full
+// id, and the HTTP surface stays the machine-to-machine one it claims to be.
+//
+// The floor is about NOISE, not safety: safety comes from the ambiguity error, since a short prefix
+// never resolves to the wrong run, only to a list. Four characters just keeps `jr2 status a` from
+// printing the whole table.
+
+import { JR2HttpError, RESOLVE_PATH, type InstanceIdentity, type JR2Client } from "./client.ts";
+
+/** Below this, a prefix is a table scan rather than a question. Mirrors the orchestrator's guard. */
+const MIN_PREFIX = 4;
+
+/** A full run id: matched on SHAPE, not `length === 36`, so a 36-character non-uuid takes the error
+ * path here instead of 404-ing off an addressed route. */
+const RUN_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/**
+ * A resolved argument, or the message + exit code to report. A result rather than a throw: throwing
+ * would route through `cli.ts`'s catch and flatten everything to exit 1, losing the split between a
+ * malformed argument (2, usage) and server state (1, runtime).
+ */
+export type ResolvedRunId = { ok: true; runId: string } | { ok: false; code: 1 | 2; message: string };
+
+/**
+ * What to say when the deployed instance has no prefix-resolution route. Names the workaround
+ * (a full id short-circuits before any resolve traffic) AND the fix, in that order: the user is
+ * mid-task, and `jr2 up` is a rollout they may not want this second.
+ */
+function skewMessage(given: string, instance?: InstanceIdentity): string {
+  const deployed = instance?.version
+    ? `deployed instance: ${instance.version}${instance.hash ? ` (${instance.hash})` : ""}`
+    : "the deployed instance predates it";
+  return [
+    `error: this instance does not support abbreviated run ids ("${given}")`,
+    `  ${deployed}`,
+    "  use the full run id, or run `jr2 up` to converge the cluster to this kit",
+  ].join("\n");
+}
+
+/**
+ * Turn a user-typed run id — full or abbreviated — into a full one. A full id short-circuits, so
+ * scripted pipelines (`jr2 run --detach | jq -r .runId` → `jr2 status $id`) issue exactly the traffic
+ * they issue today.
+ */
+export async function resolveRunId(client: JR2Client, given: string): Promise<ResolvedRunId> {
+  if (RUN_ID.test(given)) return { ok: true, runId: given };
+
+  if (given.length < MIN_PREFIX) {
+    return { ok: false, code: 2, message: `jr2: run id "${given}" is too short (need ${MIN_PREFIX}+ characters)` };
+  }
+
+  let runIds: string[];
+  let truncated: boolean;
+  try {
+    ({ runIds, truncated } = await client.candidates(given));
+  } catch (err) {
+    // A 404 on `/runs/resolve` is unreachable on an instance that HAS the route — the route is
+    // static and answers `{ runIds: [] }` when nothing matches. So a 404 here means the request fell
+    // through to `/runs/:runId`, which captured the literal string "resolve" and 404'd naming it:
+    // this instance predates abbreviated run ids. Left uncaught, that reads as `no run "resolve"` —
+    // an error about a run the user never asked for.
+    if (err instanceof JR2HttpError && err.status === 404 && err.path === RESOLVE_PATH) {
+      return { ok: false, code: 1, message: skewMessage(given, err.instance) };
+    }
+    throw err;
+  }
+
+  if (runIds.length === 0) return { ok: false, code: 1, message: `no run "${given}"` };
+  if (runIds.length === 1) return { ok: true, runId: runIds[0] as string };
+
+  const listed = runIds.map((id) => `    ${id}`).join("\n");
+  const more = truncated ? "\n    …" : "";
+  return {
+    ok: false,
+    code: 1,
+    message: `error: run id "${given}" is ambiguous\n  candidates:\n${listed}${more}`,
+  };
+}

package/src/sse.ts

@@ -0,0 +1,41 @@
+// A minimal Server-Sent-Events frame parser over a `ReadableStream<Uint8Array>` (the body the
+// orchestrator's `streamSSE` produces). Just enough of the SSE grammar for this surface: frames are
+// separated by a blank line; within a frame `event:` names the channel (default "message") and one or
+// more `data:` lines form the payload. We don't need ids, retry, or comments.
+//
+// Cancelling the reader in `finally` means a consumer that `break`s out of `for await` closes the
+// underlying HTTP connection — that is how `jr2 run` / `jr2 logs` detach without killing the run.
+
+export type SSEFrame = { event: string; data: string };
+
+export async function* parseSSE(body: ReadableStream<Uint8Array>): AsyncGenerator<SSEFrame> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      let sep: number;
+      while ((sep = buf.indexOf("\n\n")) !== -1) {
+        const frame = parseFrame(buf.slice(0, sep));
+        buf = buf.slice(sep + 2);
+        if (frame) yield frame;
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+}
+
+/** Parse one frame's lines into `{ event, data }`; returns undefined for a frame with no data. */
+function parseFrame(block: string): SSEFrame | undefined {
+  let event = "message";
+  const data: string[] = [];
+  for (const line of block.split("\n")) {
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    else if (line.startsWith("data:")) data.push(line.slice(5).trim());
+  }
+  return data.length ? { event, data: data.join("\n") } : undefined;
+}