@jr2/cli 0.1.0

package/src/commands/init.ts

@@ -0,0 +1,238 @@
+// `jr2 init [dir] [--name <n>]` (ADR-0009): scaffold a new instance folder — the minimum `jr2 up`
+// can converge and `jr2 run` can drive. v1 scope: the root marker (`jr2.config.ts`), a package.json, a
+// `tsconfig.json` the instance typechecks against (an editor's language service reads it, and so
+// does `jr2 up`, which refuses to converge a folder the compiler rejects — ADR-0050), a
+// `.gitignore` for the runtime `.jr2/`, ONE starter workflow (`ping`) that runs end-to-end with no
+// Workspace/Agent — a small "respond directly" Machine to trim down and build on — and
+// `images/default/Dockerfile`, the Sandbox Image every Workspace falls back to (ADR-0037).
+//
+// What it does NOT scaffold is as deliberate: there is no `agents/` folder and no `images/` scan,
+// because a Machine carries its own Agents and Sandbox Images (ADR-0049) and only what the CLI
+// names by string is discovered from files (ADR-0050). `workflows/` is the one discovered folder.
+//
+// Templates mirror `templates/default/` verbatim (that folder is the model instance, ADR-0054) —
+// byte-for-byte except package.json's `name`/`description`, which are per-instance.
+// `test/init.test.ts` enforces that; without it the two drift silently, and since the manifest
+// carries KIT_VERSION that same test is the version-bump tripwire (bump the kit, re-render the
+// template). Existing files are left untouched (init is additive); created paths are reported on
+// stderr.
+//
+// ONE template serves both checkout and installed mode (ADR-0043) — a branch there would mean the
+// tested output and the shipped output diverge. So the scaffold names no package manager, and pins
+// @jr2/* at the exact running KIT_VERSION: 0.x minors break, and the checkout resolves that literal
+// to its own packages via `linkWorkspacePackages: true`.
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { KIT_VERSION } from "@jr2/orchestrator";
+import { activity, type Io } from "../output.ts";
+
+export async function init(args: string[], io: Io): Promise<number> {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: false,
+    options: { name: { type: "string" } },
+  });
+
+  const dir = positionals[0] ? resolve(io.cwd, String(positionals[0])) : io.cwd;
+  const name = (values.name as string | undefined) ?? basename(dir);
+
+  const files: Array<{ path: string; content: string }> = [
+    { path: "package.json", content: packageJson(name) },
+    { path: "tsconfig.json", content: TSCONFIG_JSON },
+    { path: "jr2.config.ts", content: CONFIG_TS },
+    { path: ".gitignore", content: GITIGNORE },
+    { path: join("workflows", "ping.ts"), content: PING_TS },
+    { path: join("images", "default", "Dockerfile"), content: IMAGE_DOCKERFILE },
+  ];
+
+  activity(io, `jr2 init — scaffolding ${name} in ${dir}`);
+  for (const file of files) {
+    const full = join(dir, file.path);
+    if (await exists(full)) {
+      activity(io, `  skip   ${file.path} (exists)`);
+      continue;
+    }
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, file.content);
+    activity(io, `  create ${file.path}`);
+  }
+  activity(io, "done — install dependencies (npm, pnpm, or bun), then `jr2 up` and `jr2 run ping`");
+  return 0;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await readFile(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The scaffold declares the tool every script it writes runs. `typescript` is the one that had to
+// be learned the hard way, and `jr2 up` now RUNS this compiler as a converge gate (ADR-0050), so it
+// is load-bearing twice over: the scaffold ships a `typecheck` script but named no compiler, so `tsc`
+// resolved to whatever happened to be hoisted — in an installed instance that is `@jr2/cli`'s own
+// transitive `ts-blank-space` → `typescript`, which floats across MAJORS. A scaffolded folder
+// checked its kit's sources with a compiler the kit never ran, and reported ~120 errors in
+// @jr2/orchestrator that the kit's own gate does not see. The range is the kit's own (ADR-0043's
+// rule for `@jr2/*`, applied to the checker): the instance's PROGRAM includes the kit's `.ts`
+// sources — zero-build, `exports` point at source — so the compiler is part of the contract, not
+// the user's choice, and it moves when the kit moves.
+function packageJson(name: string): string {
+  return `${JSON.stringify(
+    {
+      name,
+      version: "0.0.0",
+      private: true,
+      type: "module",
+      scripts: { typecheck: "tsc --noEmit" },
+      dependencies: { "@jr2/orchestrator": KIT_VERSION, xstate: "^5.18.0" },
+      devDependencies: { "@jr2/cli": KIT_VERSION, "@types/node": "^26.0.1", typescript: "^5.6.0" },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+// The instance's compiler options live in @jr2/orchestrator, not here: a scaffolded folder resolves
+// them from node_modules, so they arrive with the dependency and stay in step with the engine.
+const TSCONFIG_JSON = `{
+  "extends": "@jr2/orchestrator/tsconfig.instance.json",
+  "include": ["**/*.ts"]
+}
+`;
+
+const CONFIG_TS = `import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  git: {
+    // The fence (ADR-0051): a per-run repo url — run input, a ticket field — must match an entry here or the
+    // attach refuses it, so nothing can spend this cluster's credential against an arbitrary host. \`*\` is
+    // today's two implicit defaults made visible (JR2_GIT_TOKEN from .env for https, the jr2-git-ssh Secret
+    // for ssh). Narrow it to your hosts (\`match: "github.com/yourorg/"\`) before anything untrusted can start
+    // a run. The longest match wins; the url's scheme picks token vs sshKey.
+    credentials: [{ match: "*", token: "JR2_GIT_TOKEN", sshKey: "jr2-git-ssh" }],
+  },
+  // Where Sandboxes land (ADR-0052): by default wherever an ordinary pod lands — not cordoned, no taint — and
+  // the Repo cache agent follows the same set. No node label is needed. To admit a tainted pool or narrow to
+  // a labeled one, name it in raw pod-spec shapes; \`jr2 up\` reports the Sandbox nodes it sees.
+  // sandbox: { nodeSelector: { pool: "agents" }, tolerations: [{ key: "gpu", operator: "Exists" }] },
+});
+`;
+
+// The scaffolded Sandbox Image (ADR-0037). Scaffolding it is the point: `images/default` is the
+// middle leg of the resolution chain (a `workspace()`'s `image` option → `images/default` → the
+// stock Harness), so writing it out makes the fallback a visible convention rather than magic — and
+// it is the ONE path jr2 still checks by convention, so a local Machine never has to spell
+// `import.meta.resolve("../images/default")` for its own instance's toolchain. It has
+// ZERO jr2 knowledge by contract — no ARG, no `FROM jr2-harness`, nothing about /opt/jr2 — because jr2
+// injects its runtime at POD time and never builds a stage on top of this file. It also satisfies
+// the floor by construction — a glibc base with git — so the `preflight` init step that proves it
+// at the pod's first provision passes without the author ever meeting it.
+const IMAGE_DOCKERFILE = `# A Sandbox Image (ADR-0037): the tools your agents can reach, and the shell you get when you
+# \`kubectl exec\` into a running Workspace. This file is yours — jr2 never rewrites it and reads
+# nothing out of it.
+#
+# The build context is THIS directory (\`images/default/\`), so \`COPY\` paths are relative to it and
+# nothing outside it can invalidate the image's content hash.
+#
+# jr2 never builds on top of this file. Your image is run byte-for-byte: jr2 mounts its own runtime
+# at /opt/jr2 when the pod starts and overrides the container's COMMAND to launch the Harness from
+# there, appending (never prepending) /opt/jr2/bin to PATH — so a toolchain YOU pin wins. Your
+# \`USER\` and \`HOME\` are respected, dotfiles included; declare neither and the pod runs uid 1000
+# with HOME=/home/jr2. Your \`ENTRYPOINT\`/\`CMD\` simply do not run — a container has one command and
+# the Harness must own it. A process you need running anyway gets its own seat: the User Container
+# (\`user:\` on \`workspace()\`, ADR-0005).
+#
+# Two things jr2 cannot vendor, both proven by \`jr2 up\` before it converges:
+#   - \`git\` — the agent clones, worktrees, and commits with the git you chose;
+#   - a glibc base no older than jr2's node. alpine/musl cannot run it at all.
+#
+# This one folder is a path convention; there is no \`images/\` scan (ADR-0049/0050). A SECOND Sandbox
+# Image is a docker context that travels with the Machine that names it — put the folder beside the
+# workflow module and pass \`image: import.meta.resolve("./my-image")\` to \`workspace()\`, and \`jr2 up\`
+# finds it by walking the registered Machines. \`image\` also takes a registry REF (anything that is
+# not a \`file:\` URL) for an image you baked and host yourself, which jr2 never builds. This instance
+# builds it once a registered Machine composes a Sandbox (a \`workspace()\` with \`repos\`).
+
+FROM node:24-slim
+
+RUN apt-get update \\
+  && apt-get install -y --no-install-recommends git ca-certificates \\
+  && rm -rf /var/lib/apt/lists/*
+
+# Your agents' toolchain goes here — compilers, CLIs, language servers, dotfiles.
+`;
+
+const GITIGNORE = `# Runtime state the orchestrator writes under the instance root (ADR-0009): the sqlite snapshot store
+# and the dev server's live address. Never checked in.
+.jr2/
+node_modules/
+
+# Deployment-varying values + creds this instance's jr2.config.ts reads from the environment; the
+# \`jr2\` CLI loads this file automatically (ADR-0019). Never checked in.
+.env
+`;
+
+const PING_TS = `// The simplest jr2 workflow: no Agent, no Workspace, no data plane at all. A Machine is free to "just
+// respond to the request" with a plain actor (CONTEXT.md: a workflow need not spawn a Workspace) —
+// this is that case, and the one workflow that runs end-to-end on a fresh instance before any Sandbox /
+// Harness infrastructure exists. Filename \`ping.ts\` → workflow "ping".
+//
+// Shape: take the run input, invoke a plain \`fromPromise\` actor, fold its result into context, finish.
+// \`jr2 run ping --input '{"message":"hi"}'\` → the run reaches \`done\` and \`jr2 status\` shows the reply.
+//
+// Module contract (ADR-0011/0015): one named export — \`machine\`. A workflow that accepts
+// external events authors with \`jr2Setup({ events: [...] })\`; ping accepts none, so plain
+// xstate \`setup()\` is all it needs.
+//
+// The next step is a Machine the kit already ships (ADR-0054). \`@jr2/machines\` exports \`task\` — one
+// prompt, one Workspace, one human says done — and a Workflow is only the name an Instance
+// registers a Machine under, so the whole of \`workflows/task.ts\` is:
+//
+//   import { customize } from "@jr2/orchestrator";
+//   import { task } from "@jr2/machines";
+//
+//   export const machine = customize(task, {
+//     repos: { target: { url: "https://github.com/you/repo.git" } },
+//     agents: { coder: { model: "anthropic/claude-sonnet-4-6" } },
+//   });
+//
+// A packaged Machine leaves the parts it cannot honestly fill OPEN: it does not know your
+// repository and cannot pay for your model. \`jr2 up\` refuses an Open part nobody bound and prints
+// the \`customize\` line that binds it, so forgetting one stops the converge instead of spending
+// money on a model you never chose. Add \`@jr2/machines\` to this folder's dependencies when you
+// write that file. \`ping\` stays Agent-free on purpose: it is the workflow that runs before any
+// model provider, Harness, or Sandbox exists.
+
+import { setup, assign, fromPromise } from "xstate";
+
+type Input = { message?: string };
+type Ctx = { message: string; reply?: string };
+
+export const machine = setup({
+  types: {} as { context: Ctx; input: Input },
+  actors: {
+    // A plain actor — no Harness, no Sandbox. Stands in for any non-Agent compute a workflow runs.
+    respond: fromPromise<string, { message: string }>(async ({ input }) => \`pong: \${input.message}\`),
+  },
+}).createMachine({
+  id: "ping",
+  context: ({ input }) => ({ message: input.message ?? "ping" }),
+  initial: "responding",
+  states: {
+    responding: {
+      invoke: {
+        src: "respond",
+        input: ({ context }) => ({ message: context.message }),
+        onDone: { target: "done", actions: assign({ reply: ({ event }) => event.output }) },
+      },
+    },
+    done: { type: "final" },
+  },
+});
+`;

package/src/commands/kit.ts

@@ -0,0 +1,141 @@
+// `jr2 kit push <registry>` (ADR-0044): the installed self-hoster's mirror of the Kit images.
+//
+// Kit images live at a canonical public home (`ghcr.io/snapwich`, baked into `publishedKitRefs()`).
+// A cluster that cannot reach it — air-gapped, mirror-only, or simply policy-bound to one registry —
+// needs the three refs at its own address, which is what `kitRegistry` names in the config. This
+// command is how the bytes get there.
+//
+// It is deliberately INSTANCE-LESS: no `jr2.config.ts`, no kube context, no namespace. Kit images are
+// shared by every instance on a cluster (and possibly by every instance in an org), so moving them
+// is its own deliberate act rather than a side effect of converging one instance — which is exactly
+// why ADR-0044 keeps this out of `jr2 up`.
+//
+// It is a MIRROR and nothing else. There is no build arm here: the npm packages carry no Harness or
+// Adapter source, and an installed CLI that could build Kit images would be the patched-Harness
+// eject hatch ADR-0027/ADR-0038 welded shut. The kit developer's arm is `just kit-push`, in the
+// checkout, where the sources actually are.
+//
+// The copy is `docker buildx imagetools create`, a registry-to-registry manifest copy: it moves the
+// full manifest list (every platform, exact digests) without landing bytes on this host. A daemon
+// -side `docker pull` + `docker push` would flatten a multi-arch image to the host's own platform
+// and ship an amd64-only image to an arm64 cluster, so it is not an implementation detail we may
+// swap — it is the decision.
+
+import { execFile } from "node:child_process";
+import { parseArgs, promisify } from "node:util";
+import { KIT_VERSION } from "@jr2/orchestrator";
+import { KIT_IMAGES, publishedKitRefs, type KitImageName } from "../build.ts";
+import { activity, result, type Io } from "../output.ts";
+
+const exec = promisify(execFile);
+
+const USAGE = `usage: jr2 kit push <registry>
+
+  mirror the v${KIT_VERSION} kit images (harness, adapter, operator) from their canonical
+  home into <registry>, for a cluster whose \`kitRegistry\` names it (ADR-0044)`;
+
+/** Run one `docker` invocation, rejecting on a non-zero exit. The seam this command is tested
+ * through: the claims are which argv each ref produces and what a failure means, and both are
+ * decidable with no registry anywhere near the test. Narrower than `build.ts`'s `RunCommand` on
+ * purpose — a mirror runs docker and only docker, and from nowhere in particular. */
+export type RunDocker = (args: string[]) => Promise<void>;
+
+const dockerCli: RunDocker = async (args) => {
+  await exec("docker", args, { maxBuffer: 64 * 1024 * 1024 });
+};
+
+/** What one image's mirror did — the per-image line, and the machine-readable result's rows. */
+type Mirrored = { image: KitImageName; source: string; target: string; copied: boolean };
+
+export async function kit(args: string[], io: Io, docker: RunDocker = dockerCli): Promise<number> {
+  const { positionals } = parseArgs({ args, allowPositionals: true, strict: false, options: {} });
+  const [sub, registry] = positionals;
+
+  if (sub !== "push") {
+    activity(io, sub === undefined ? "jr2 kit: no subcommand" : `unknown kit subcommand: ${sub}`);
+    activity(io, USAGE);
+    return 2;
+  }
+  if (!registry) {
+    activity(io, "jr2 kit push: no target registry");
+    activity(io, USAGE);
+    return 2;
+  }
+
+  // A trailing slash is the one spelling a human types and no registry accepts.
+  const target = registry.replace(/\/+$/, "");
+
+  // Both ends come out of `publishedKitRefs`: bare, it is the canonical home; given a registry, it
+  // is what that registry re-homes the refs to — which is precisely what a converge with
+  // `kitRegistry: <target>` will ask its nodes to pull. So the mirror cannot fill an address the
+  // deployment does not read, and neither side of ADR-0044 can drift from the other.
+  const sources = publishedKitRefs();
+  const targets = publishedKitRefs(target);
+
+  activity(io, `jr2 kit push — mirroring the v${KIT_VERSION} kit images to ${target}`);
+  const rows: Mirrored[] = [];
+  for (const image of Object.keys(KIT_IMAGES) as KitImageName[]) {
+    rows.push(await mirror(io, docker, image, sources[image], targets[image]));
+  }
+
+  const copied = rows.filter((r) => r.copied).length;
+  activity(io, `mirrored ${copied} image(s), ${rows.length - copied} already present`);
+  result(io, {
+    registry: target,
+    version: KIT_VERSION,
+    images: Object.fromEntries(rows.map((r) => [r.image, r.target])),
+  });
+  return 0;
+}
+
+/**
+ * One image, skip-checked first. A published version tag never moves — the release train ties it to
+ * one npm version (ADR-0019) — so a tag already resolving in the target is not merely present, it is
+ * CURRENT, and re-copying it would buy nothing. That is also why this asks the target before the
+ * source: the common repeat run costs one inspect and no transfer at all.
+ */
+async function mirror(
+  io: Io,
+  docker: RunDocker,
+  image: KitImageName,
+  source: string,
+  target: string,
+): Promise<Mirrored> {
+  if (await resolves(docker, target)) {
+    activity(io, `${image}: already present — ${target}`);
+    return { image, source, target, copied: false };
+  }
+  await requireSource(docker, image, source, target);
+  await docker(["buildx", "imagetools", "create", "-t", target, source]);
+  activity(io, `${image}: copied ${source} → ${target}`);
+  return { image, source, target, copied: true };
+}
+
+/** Does this ref resolve in its registry? `imagetools inspect` reads the manifest and nothing else,
+ * so the question costs a metadata round-trip rather than a pull. Any failure reads as "not there":
+ * a registry that cannot answer is one this command must not assume it has already filled, and the
+ * copy that follows fails loudly enough for both cases. */
+async function resolves(docker: RunDocker, ref: string): Promise<boolean> {
+  try {
+    await docker(["buildx", "imagetools", "inspect", ref]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The missing-source failure, named on both ends. It is the common case in a dev loop — the home has
+ * nothing at `0.0.0`, and nothing ever will — so the message must not read as a broken mirror. What
+ * it points at is the other arm of ADR-0044: `just kit-push`, in the checkout, is what puts images
+ * at a published name in the first place; this command only moves what is already there.
+ */
+async function requireSource(docker: RunDocker, image: KitImageName, source: string, target: string): Promise<void> {
+  if (await resolves(docker, source)) return;
+  throw new Error(
+    `${image}: ${source} is not there, so nothing can be mirrored to ${target}\n` +
+      `  a kit image reaches ${target} only by being copied from its published home;\n` +
+      `  if v${KIT_VERSION} was never published (a dev version never is), seed a registry from a kit\n` +
+      `  checkout with \`just kit-push <registry>\`, which builds the three images from source`,
+  );
+}

package/src/commands/logs.ts

@@ -0,0 +1,50 @@
+// `jr2 logs <runId|abbrev> [-f]` (ADR-0009): re-attach to a run's feed. The orchestrator replays the current
+// status on attach, so even without -f you see where the run IS right now (status → stdout as JSON;
+// author emits → stderr). `-f`/`--follow` keeps streaming status deltas until the run settles; without
+// it, we print the replayed status and stop. A run that already settled streams its final status once.
+
+import { parseArgs } from "node:util";
+import { JR2Client } from "../client.ts";
+import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
+import { activity, result, type Io } from "../output.ts";
+import { resolveRunId } from "../run-id.ts";
+
+export async function logs(args: string[], io: Io): Promise<number> {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: false,
+    options: { follow: { type: "boolean", short: "f" }, ...TARGET_ARGS },
+  });
+  const given = positionals[0];
+  if (!given) {
+    activity(io, "usage: jr2 logs <runId|abbrev> [-f]");
+    return 2;
+  }
+  const target = await resolveTarget(io, targetOptions(values));
+  try {
+    const client = new JR2Client(target.url, io.fetch, target.token);
+    const ref = await resolveRunId(client, given);
+    if (!ref.ok) {
+      activity(io, ref.message);
+      return ref.code;
+    }
+
+    for await (const ev of client.events(ref.runId)) {
+      if (ev.kind === "emit") {
+        activity(io, `emit ${JSON.stringify(ev.event)}`);
+        continue;
+      }
+      if (ev.kind === "retry") {
+        activity(io, `retry ${ev.child} attempt ${ev.attempt} (${ev.reason})`);
+        continue;
+      }
+      result(io, ev.status);
+      if (!values.follow) break;
+      if (ev.status.status !== "active") break;
+    }
+    return 0;
+  } finally {
+    target.close?.();
+  }
+}

package/src/commands/run.ts

@@ -0,0 +1,64 @@
+// `jr2 run <workflow> [--input <json>] [--detach]` (ADR-0009). BLOCKING + attach-by-default, mirroring
+// `flue run`: start the run, then attach to its SSE feed — status deltas + author emits go to stderr
+// as they happen; the terminal RunStatus is printed as JSON on stdout and we exit. So `jr2 run ping`
+// shows progress to a human while `jr2 run ping | jq` yields just the result.
+//
+// Diverges from flue: this ATTACHES to the deployed orchestrator (port-forwarded via the current
+// kube context — ADR-0019) rather than a per-invocation runtime, because jr2 runs are durable and may
+// park indefinitely on an approval gate. `--detach` prints the runId and returns, leaving the run
+// going server-side.
+
+import { parseArgs } from "node:util";
+import { JR2Client } from "../client.ts";
+import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
+import { activity, result, type Io } from "../output.ts";
+
+export async function run(args: string[], io: Io): Promise<number> {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      input: { type: "string" },
+      detach: { type: "boolean" },
+      ...TARGET_ARGS,
+    },
+  });
+
+  const workflow = positionals[0];
+  if (!workflow) {
+    activity(io, "usage: jr2 run <workflow> [--input <json>] [--detach]");
+    return 2;
+  }
+  const input = values.input ? (JSON.parse(String(values.input)) as Record<string, unknown>) : {};
+  const target = await resolveTarget(io, targetOptions(values));
+  try {
+    const client = new JR2Client(target.url, io.fetch, target.token);
+
+    const { runId } = await client.start(workflow, input);
+    if (values.detach) {
+      result(io, { runId });
+      return 0;
+    }
+
+    activity(io, `run ${runId} (${workflow}) — attached`);
+    for await (const ev of client.events(runId)) {
+      if (ev.kind === "emit") {
+        activity(io, `  emit ${JSON.stringify(ev.event)}`);
+        continue;
+      }
+      if (ev.kind === "retry") {
+        activity(io, `  retry ${ev.child} attempt ${ev.attempt} (${ev.reason})`);
+        continue;
+      }
+      activity(io, `  → ${ev.status.status} ${JSON.stringify(ev.status.value)}`);
+      if (ev.status.status !== "active") {
+        result(io, ev.status);
+        return ev.status.status === "error" ? 1 : 0;
+      }
+    }
+    return 0;
+  } finally {
+    target.close?.();
+  }
+}

package/src/commands/runs.ts

@@ -0,0 +1,19 @@
+// `jr2 runs` (ADR-0009): list the live runs as JSON on stdout. (Settled runs leave the live registry;
+// read a specific one through to the store with `jr2 status <runId>`.)
+
+import { parseArgs } from "node:util";
+import { JR2Client } from "../client.ts";
+import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
+import { result, type Io } from "../output.ts";
+
+export async function runs(args: string[], io: Io): Promise<number> {
+  const { values } = parseArgs({ args, allowPositionals: true, strict: false, options: { ...TARGET_ARGS } });
+  const target = await resolveTarget(io, targetOptions(values));
+  try {
+    const client = new JR2Client(target.url, io.fetch, target.token);
+    result(io, await client.list());
+    return 0;
+  } finally {
+    target.close?.();
+  }
+}

package/src/commands/send.ts

@@ -0,0 +1,83 @@
+// `jr2 send` (ADR-0009/0011/0013): the two down-channels a human has into a live run.
+//
+//   jr2 send <runId|abbrev> --event CANCEL                           run control (the only verb left)
+//   jr2 send <runId|abbrev> --gate <gate> --event <name> [--input '<json>'] deliver to an open Gate
+//
+// Run control used to carry APPROVE and STEER too. Those rode the `deferred` (held tool result)
+// and `poll` (steer inbox) semantics, which ADR-0013 reserves but does not build — so they are
+// gone rather than left pretending. Workflow-defined events reach a run through its GATES
+// (`POST /runs/:id/gates/:gate/events` — ADR-0011): the gate names the pending decision, the
+// event name must be in its derived accepts, and the input is validated against the event's
+// schema host-side. Discover a run's open gates (names + accepts + meta) with `jr2 status <runId>`.
+//
+// The run id resolves BEFORE either branch: both are writes, and a write must never be
+// prefix-sensitive (ADR-0009). It also gives a bad id a real error — `host.stop()` returns silently
+// for an unknown run, so an unresolved CANCEL used to report success.
+
+import { parseArgs } from "node:util";
+import { JR2Client } from "../client.ts";
+import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
+import { activity, type Io } from "../output.ts";
+import { resolveRunId } from "../run-id.ts";
+
+const USAGE =
+  "usage: jr2 send <runId|abbrev> --event CANCEL | jr2 send <runId|abbrev> --gate <gate> --event <name> [--input '<json>']";
+
+export async function send(args: string[], io: Io): Promise<number> {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      event: { type: "string" },
+      gate: { type: "string" },
+      input: { type: "string" },
+      ...TARGET_ARGS,
+    },
+  });
+  const given = positionals[0];
+  const gate = values.gate as string | undefined;
+  const event = values.event as string | undefined;
+  if (!given || !event) {
+    activity(io, USAGE);
+    return 2;
+  }
+  const target = await resolveTarget(io, targetOptions(values));
+  try {
+    const client = new JR2Client(target.url, io.fetch, target.token);
+    const ref = await resolveRunId(client, given);
+    if (!ref.ok) {
+      activity(io, ref.message);
+      return ref.code;
+    }
+    const runId = ref.runId;
+
+    // Gate delivery: the event name is the workflow's own vocabulary — case-preserved, never
+    // normalized here (the host validates it against the gate's accepts).
+    if (gate) {
+      let input: Record<string, unknown> = {};
+      if (values.input !== undefined) {
+        try {
+          input = JSON.parse(values.input as string) as Record<string, unknown>;
+        } catch {
+          activity(io, `jr2 send: --input is not valid JSON`);
+          return 2;
+        }
+      }
+      await client.sendToGate(runId, gate, { type: event, ...input });
+      activity(io, `delivered ${event} to gate "${gate}" on ${runId}`);
+      return 0;
+    }
+
+    const control = event.toUpperCase();
+    if (control !== "CANCEL") {
+      activity(io, `jr2 send: unknown event "${event}" (run control accepts: CANCEL; workflow events need --gate)`);
+      return 2;
+    }
+    await client.send(runId, { type: control });
+    activity(io, `sent ${control} to ${runId}`);
+    return 0;
+  } finally {
+    target.close?.();
+  }
+}