@jr2/cli 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/cli",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "The jr2 CLI: init, up, run — the interface to a jr2 Instance.",
   "license": "MIT",
   "private": false,
@@ -39,13 +39,13 @@
     "ts-blank-space": "^0.9.0"
   },
   "peerDependencies": {
-    "@jr2/orchestrator": "0.1.3"
+    "@jr2/orchestrator": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/orchestrator": "0.1.3"
+    "@jr2/orchestrator": "0.2.0"
   },
   "files": [
     "bin",

package/src/cli.ts

@@ -15,11 +15,14 @@ import { up } from "./commands/up.ts";
 import { down } from "./commands/down.ts";
 import { gc } from "./commands/gc.ts";
 import { kit } from "./commands/kit.ts";
+import { version } from "./commands/version.ts";
 
 const USAGE = `jr2 — orchestrate agentic workflows (ADR-0009)
 
 usage: jr2 <command> [args]
 
+  version [--local] [--json]        what runs here (this jr2, the global that handed off, the
+                                    Instance's Kit) and what the cluster runs; --local skips the cluster
   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)
@@ -30,7 +33,7 @@ usage: jr2 <command> [args]
        [--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)
+         [--json]                   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>]
@@ -40,7 +43,11 @@ run ids: any <runId> above may be abbreviated to a unique prefix (4+ chars, git-
          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)`;
+                    --url <u> / JR2_URL attaches to a specific orchestrator (skips kube entirely)
+
+output: result verbs (run, runs, status <runId>, send, logs) print one JSON result on stdout and
+        activity on stderr, so \`jr2 run … | jq\` yields the result; report verbs (version, bare
+        status) print a table on stdout, or the one object with --json`;
 
 /**
  * The catch-all half of skew reporting: a route-shaped failure gets ONE extra line naming what the
@@ -88,6 +95,9 @@ export async function main(argv: string[], io: Io = defaultIo): Promise<number>
         return await gc(rest, io);
       case "kit":
         return await kit(rest, io);
+      case "version":
+      case "--version":
+        return await version(rest, io);
       case "help":
       case "--help":
       case "-h":

package/src/commands/status.ts

@@ -6,8 +6,13 @@
 // unregistered deploy key (ADR-0047), a wrong url, a git host outage — is discoverable by asking
 // the thing that knows, rather than by tailing pod logs. The Orchestrator serves either way; only
 // the Repo is degraded, and the cache agent retries it on its own.
+//
+// Two output classes (ADR-0009 as amended): `status <runId>` is a RESULT verb — the RunStatus as one
+// JSON line on stdout, for the pipe. Bare `status` is a REPORT verb — a human table on stdout, or the
+// one object with `--json`.
 
 import { parseArgs } from "node:util";
+import type { RepoStatus } from "@jr2/orchestrator";
 import { JR2Client } from "../client.ts";
 import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
 import { activity, result, type Io } from "../output.ts";
@@ -18,7 +23,7 @@ export async function status(args: string[], io: Io): Promise<number> {
     args,
     allowPositionals: true,
     strict: false,
-    options: { ...TARGET_ARGS },
+    options: { ...TARGET_ARGS, json: { type: "boolean" } },
   });
   // NO run named, not an EMPTY one: `jr2 status "$RUNID"` with the variable unset asked about a run
   // and got an empty string, and answering that with the instance's repos would report exit 0 on a
@@ -27,7 +32,7 @@ export async function status(args: string[], io: Io): Promise<number> {
   const target = await resolveTarget(io, targetOptions(values));
   try {
     const client = new JR2Client(target.url, io.fetch, target.token);
-    if (given === undefined) return await instanceStatus(client, io);
+    if (given === undefined) return await instanceStatus(client, io, values.json === true);
     const ref = await resolveRunId(client, given);
     if (!ref.ok) {
       activity(io, ref.message);
@@ -46,11 +51,11 @@ export async function status(args: string[], io: Io): Promise<number> {
 }
 
 /**
- * The instance's own status: the data-plane switch and every Repo resource, on stdout as one JSON
- * object (extensible — the instance has more to report eventually), and every node whose last
- * attempt on a Repo FAILED spelled out on stderr with git's own error, since that is the line a
- * human acts on. An instance with no data plane says so — "no registered Machine composes a
- * Sandbox" is the answer, not an empty list.
+ * The instance's own status: the data-plane switch and every Repo resource. As a table on stdout —
+ * every node's state per Repo, and every node whose last attempt FAILED spelled out with git's own
+ * error, since that is the line a human acts on — or, with `--json`, as the one object (extensible:
+ * the instance has more to report eventually). An instance with no data plane says so — "no
+ * registered Machine composes a Sandbox" is the answer, not an empty list.
  *
  * Two failures, two consequences (ADR-0004/0051): a cache that is ABSENT on the node (a cold clone
  * failed) parks every Workspace that needs it there; a cache that is PRESENT but whose last fetch
@@ -60,31 +65,40 @@ export async function status(args: string[], io: Io): Promise<number> {
  * Exit 0 even with Repos failing: this is a report, and a degraded Repo is a state the instance
  * is serving in, not a failure of the asking.
  */
-async function instanceStatus(client: JR2Client, io: Io): Promise<number> {
-  const { dataPlane, repos } = await client.repos();
-  if (!dataPlane) activity(io, "this instance has no data plane (no registered Machine composes a Sandbox)");
+async function instanceStatus(client: JR2Client, io: Io, json: boolean): Promise<number> {
+  const report = await client.repos();
+  if (json) result(io, report);
+  else io.stdout(renderInstanceStatus(report));
+  return 0;
+}
+
+/** The human table — one line per Repo, one per node under it, then the hints for what was seen. */
+export function renderInstanceStatus({ dataPlane, repos }: { dataPlane: boolean; repos: RepoStatus[] }): string {
+  let out = dataPlane
+    ? "data plane: yes\n"
+    : "data plane: none — this instance has no data plane (no registered Machine composes a Sandbox)\n";
   let absent = 0;
   let stale = 0;
   for (const repo of repos) {
+    out += `repo ${repo.key} (${repo.url})${repo.bound ? "  bound" : ""}\n`;
     for (const node of repo.nodes) {
-      if (node.synced || node.lastError === undefined) continue;
-      if (node.present) stale++;
-      else absent++;
-      activity(
-        io,
-        `repo ${repo.key} (${repo.url}) on node ${node.node}: ${node.present ? "stale" : "absent"} — ${node.lastError}`,
-      );
+      if (node.synced) {
+        out += `  node ${node.node}: present, synced\n`;
+      } else if (node.lastError === undefined) {
+        out += `  node ${node.node}: ${node.present ? "present" : "absent"}, not yet fetched\n`;
+      } else {
+        if (node.present) stale++;
+        else absent++;
+        out += `  node ${node.node}: ${node.present ? "stale" : "absent"} — ${node.lastError}\n`;
+      }
     }
   }
   if (absent || stale) {
-    activity(
-      io,
+    out +=
       "the cache agent keeps retrying these — register the deploy key with your git host, or fix the url or the " +
-        "git.credentials entry, and the next attempt lands (ADR-0047/0048/0051).",
-    );
+      "git.credentials entry, and the next attempt lands (ADR-0047/0048/0051).\n";
   }
-  if (absent) activity(io, "absent: Workspaces needing that cache on that node wait until it lands.");
-  if (stale) activity(io, "stale: attaches proceed on what the cache holds until the next fetch lands.");
-  result(io, { dataPlane, repos });
-  return 0;
+  if (absent) out += "absent: Workspaces needing that cache on that node wait until it lands.\n";
+  if (stale) out += "stale: attaches proceed on what the cache holds until the next fetch lands.\n";
+  return out;
 }

package/src/commands/up.ts

@@ -1361,13 +1361,19 @@ async function preflightProvider(
           `${err instanceof Error ? err.message : err}\n` +
           `  - localhost never works from a pod; use a LAN address\n` +
           `  - the model id must be exactly what the endpoint serves (vLLM: GET /v1/models)\n` +
-          `  - vLLM needs --enable-auto-tool-choice and a matching --tool-call-parser`,
+          `  - vLLM needs --enable-auto-tool-choice and a matching --tool-call-parser\n` +
+          `  - finish_reason "length" means the model ran out of tokens before the call (a thinking model reasons first)`,
       );
     }
   }
 }
 
-/** The in-cluster probe: GET /models, then one chat completion that must answer with tool_calls. */
+/**
+ * The in-cluster probe: GET /models, then one chat completion that must answer with tool_calls. The budget
+ * is generous because a thinking model (Qwen3, DeepSeek-R1) reasons BEFORE it calls the tool, and that
+ * reasoning counts against max_tokens — at 64 the completion ended with finish_reason "length" and an
+ * empty tool_calls, which read as "the endpoint cannot call tools" when it could.
+ */
 function providerProbeScript(baseUrl: string, model: string, apiKey?: string): string {
   const base = JSON.stringify(baseUrl.replace(/\/+$/, ""));
   const headers = apiKey
@@ -1378,14 +1384,15 @@ function providerProbeScript(baseUrl: string, model: string, apiKey?: string): s
     `const m = await fetch(${base} + "/models", { headers: h });` +
     `if (!m.ok) throw new Error("GET /models: HTTP " + m.status);` +
     `const c = await fetch(${base} + "/chat/completions", { method: "POST", headers: h, body: JSON.stringify({` +
-    ` model: ${JSON.stringify(model)}, max_tokens: 64,` +
+    ` model: ${JSON.stringify(model)}, max_tokens: 1024,` +
     ` messages: [{ role: "user", content: "Call the ping tool." }],` +
     ` tools: [{ type: "function", function: { name: "ping", description: "reply with a ping", parameters: { type: "object", properties: {} } } }]` +
     ` }) });` +
     `const j = await c.json();` +
     `if (!c.ok) throw new Error("POST /chat/completions: HTTP " + c.status + " " + JSON.stringify(j).slice(0, 300));` +
-    `const calls = j.choices?.[0]?.message?.tool_calls;` +
-    `if (!calls?.length) throw new Error("completion carried no tool_calls");` +
+    `const choice = j.choices?.[0];` +
+    `const calls = choice?.message?.tool_calls;` +
+    `if (!calls?.length) throw new Error("completion carried no tool_calls (finish_reason " + JSON.stringify(choice?.finish_reason ?? null) + ")");` +
     `console.log("PROVIDER OK");`
   );
 }

package/src/commands/version.ts

@@ -0,0 +1,331 @@
+// `jr2 version [--local] [--json]` (ADR-0009 as amended): the report you paste into a bug. What is
+// HERE — the copy that runs, the global that handed off (ADR-0056), the Instance's Kit version, the
+// Instance and its mode, node — and what is DEPLOYED — the orchestrator the pod says it is, the
+// operator, the Kit images pods read — side by side, so the gap between the halves is the answer
+// ("you edited the pin and never ran `jr2 up`").
+//
+// The one Instance verb that reads the Instance without asserting it: a Kit mismatch is a LINE here,
+// never the ADR-0056 refusal, because this is the verb you reach for when that refusal fires. Every
+// probe is best-effort and every answer is a report — exit 0 whatever it finds. Nothing here
+// computes what `jr2 up` computes: no bundle staging, no local content hash.
+//
+// A REPORT verb, not a result verb: the human table goes to stdout, `--json` swaps in the one object.
+
+import { basename } from "node:path";
+import { parseArgs } from "node:util";
+import { IMAGES_CONFIGMAP, IMAGES_KEY, INSTANCE_SECRET, loadConfig, type ImageRefs } from "@jr2/orchestrator";
+import { detectKitCheckout, KIT_IMAGE_HOME } from "../build.ts";
+import type { InstanceIdentity } from "../client.ts";
+import { compareVersions, LABEL_HASH, LABEL_VERSION, OPERATOR_DEPLOYMENT, OPERATOR_NAMESPACE } from "../deploy.ts";
+import { handedOffFrom } from "../handoff.ts";
+import { TARGET_ARGS, targetOptions, type TargetOptions } from "../instance.ts";
+import { checkKitVersion, CLI_ROOT, CLI_VERSION } from "../kit-version.ts";
+import { kubectlAdmin, kubectlKube, ORCHESTRATOR_PORT, ORCHESTRATOR_SERVICE, type KubeObject } from "../kube.ts";
+import { activity, result, type Io } from "../output.ts";
+import { findRoot } from "../root.ts";
+
+/** A package as the report names it: the number and the real path, so the path says WHICH copy. */
+export type Copy = { version: string; path: string };
+
+/** The image map as `jr2 up` wrote it and pods read it (ADR-0038). */
+type Images = Partial<ImageRefs & { operator?: string }>;
+
+/** The comparison between the local kit line and the orchestrator line — the verdict the two
+ * halves exist to produce. `unknown` when either side is missing. */
+export type Skew = "same" | "behind" | "ahead" | "unknown";
+
+export type VersionReport = {
+  /** The copy that runs (after any handoff). */
+  cli: Copy;
+  /** The copy that handed off, when one did and said so (ADR-0056 as amended). */
+  global?: Copy;
+  node: string;
+  /** Absent outside an Instance; `mode` decides whether deployed Kit tags read as versions
+   * (installed) or content hashes (checkout). */
+  instance?: {
+    name: string;
+    root: string;
+    mode: "checkout" | "installed";
+    kitCheckout?: string;
+    /** Where an installed kit pulls its Kit images from: `kitRegistry`, else the canonical home. */
+    kitRegistry?: string;
+    configError?: string;
+  };
+  /** The Instance's Kit version — the `@jr2/orchestrator` it resolves — and the ADR-0056 check. */
+  kit?: {
+    version?: string;
+    path?: string;
+    /** What the manifest pins, when it disagrees with what resolves (or nothing resolves). */
+    pinned?: string;
+    check: "ok" | "mismatch" | "unresolved";
+    /** This CLI's own peer, named when the check is not `ok`. */
+    against?: Copy;
+  };
+  deployed?: {
+    url?: string;
+    context?: string;
+    namespace?: string;
+    orchestrator?: Orchestrator;
+    operator?: { version?: string; image?: string };
+    images?: Images;
+  };
+  skew?: Skew;
+};
+
+/** What the pod answers on `/healthz`, plus what the Deployment records — two facts, because a
+ * rollout that has not landed leaves them disagreeing. Or why neither could be read. */
+type Orchestrator = { version?: string; hash?: string; deploymentHash?: string; image?: string } | { error: string };
+
+export async function version(args: string[], io: Io): Promise<number> {
+  const { values } = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: false,
+    options: { ...TARGET_ARGS, local: { type: "boolean" }, json: { type: "boolean" } },
+  });
+  const opts = targetOptions(values);
+  const report = await versionReport(io, opts, { local: values.local === true });
+  if (values.json === true) result(io, report);
+  else io.stdout(render(report));
+  return 0;
+}
+
+/** The report as data — the whole verb minus its rendering, so tests read facts and not columns. */
+export async function versionReport(io: Io, opts: TargetOptions, flags: { local: boolean }): Promise<VersionReport> {
+  const report: VersionReport = {
+    cli: { version: CLI_VERSION, path: CLI_ROOT },
+    global: handedOffFrom(io.env),
+    node: process.version,
+  };
+
+  const root = findRoot(io.cwd);
+  let namespace: string | undefined;
+  if (root) {
+    const kit = checkKitVersion(root);
+    report.kit = {
+      version: kit.instance?.version,
+      path: kit.instance?.root,
+      // The pin is noise when it agrees with what resolves; it is the diagnosis when it does not.
+      pinned: kit.pinned !== undefined && kit.pinned !== kit.instance?.version ? kit.pinned : undefined,
+      check: kit.ok ? "ok" : kit.instance ? "mismatch" : "unresolved",
+      against: kit.ok || !kit.own ? undefined : { version: kit.own.version, path: kit.own.root },
+    };
+
+    // The config names the Instance (its namespace by default) and where an installed kit pulls
+    // from. A config that will not load is itself a fact worth a line — never a reason to stop.
+    let config: Awaited<ReturnType<typeof loadConfig>>;
+    let configError: string | undefined;
+    try {
+      config = await loadConfig(root);
+    } catch (e) {
+      configError = e instanceof Error ? e.message : String(e);
+    }
+    namespace = opts.namespace ?? config?.name ?? basename(root);
+    const kitCheckout = await detectKitCheckout(io.kitDir);
+    report.instance = {
+      name: config?.name ?? basename(root),
+      root,
+      mode: kitCheckout ? "checkout" : "installed",
+      kitCheckout,
+      kitRegistry: kitCheckout ? undefined : (config?.kitRegistry ?? KIT_IMAGE_HOME),
+      configError,
+    };
+  }
+
+  if (!flags.local) {
+    const url = opts.url ?? io.env.JR2_URL;
+    if (url) {
+      activity(io, `→ ${url}`);
+      report.deployed = { url, orchestrator: await probeHealthz(io, url) };
+    } else if (root && namespace) {
+      report.deployed = await probeCluster(io, opts, namespace);
+    }
+    // No Instance and no `--url`: there is nothing to address, and the local half already says so.
+  }
+
+  report.skew = skew(report);
+  return report;
+}
+
+/** `GET /healthz` — unauthenticated, so this needs no Instance token. The reason it could not be
+ * read is the answer when it fails, since an unreachable orchestrator is what a user is debugging. */
+async function probeHealthz(io: Io, url: string): Promise<Orchestrator> {
+  const fetchImpl = io.fetch ?? globalThis.fetch;
+  try {
+    const res = await fetchImpl(`${url.replace(/\/+$/, "")}/healthz`);
+    if (!res.ok) return { error: `GET /healthz answered HTTP ${res.status}` };
+    const body = (await res.json()) as InstanceIdentity;
+    return { version: body.version, hash: body.hash };
+  } catch (e) {
+    return { error: `unreachable — ${e instanceof Error ? e.message : String(e)}` };
+  }
+}
+
+/**
+ * The kube path, mirroring `resolveTarget`'s two-fault split (ADR-0019) without its refusals: a
+ * Secret read that THROWS is a cluster that cannot be reached; an EMPTY answer is an Instance not
+ * deployed there. Then the Deployment's records, the pod's own account over a port-forward, the
+ * operator's label, and the image map pods actually read — each independently best-effort.
+ */
+async function probeCluster(io: Io, opts: TargetOptions, namespace: string): Promise<VersionReport["deployed"]> {
+  const kube = io.kube ?? kubectlKube;
+  const admin = io.kubeAdmin ?? kubectlAdmin;
+  const context = opts.context ?? (await kube.currentContext());
+  const deployed: VersionReport["deployed"] = { context, namespace };
+  if (!context) {
+    deployed.orchestrator = { error: "no kube context — nothing to ask" };
+    return deployed;
+  }
+  activity(io, `→ context ${context} / namespace ${namespace}`);
+  const ctx = opts.context ? { context: opts.context } : {};
+
+  try {
+    const secret = await kube.readSecret({ namespace, name: INSTANCE_SECRET, key: "JR2_INSTANCE_TOKEN", ...ctx });
+    if (!secret) {
+      deployed.orchestrator = { error: `not deployed in ${namespace} (context ${context}) — \`jr2 up\` deploys` };
+      return deployed;
+    }
+  } catch (e) {
+    deployed.orchestrator = { error: `cannot reach the cluster — context ${context}: ${(e as Error).message}` };
+    return deployed;
+  }
+
+  const orch = await admin.getJson({ kind: "deployment", name: ORCHESTRATOR_SERVICE, namespace, ...ctx });
+  const recorded = { deploymentHash: orch?.metadata.labels?.[LABEL_HASH], image: firstImage(orch) };
+  let fwd: { url: string; close: () => void } | undefined;
+  try {
+    fwd = await kube.portForward({ namespace, service: ORCHESTRATOR_SERVICE, port: ORCHESTRATOR_PORT, ...ctx });
+    const live = await probeHealthz(io, fwd.url);
+    deployed.orchestrator = "error" in live ? live : { ...live, ...recorded };
+  } catch (e) {
+    deployed.orchestrator = { error: `port-forward failed — ${(e as Error).message}` };
+  } finally {
+    fwd?.close();
+  }
+
+  const operator = await admin.getJson({
+    kind: "deployment",
+    name: OPERATOR_DEPLOYMENT,
+    namespace: OPERATOR_NAMESPACE,
+    ...ctx,
+  });
+  if (operator) {
+    deployed.operator = { version: operator.metadata.labels?.[LABEL_VERSION], image: firstImage(operator) };
+  }
+
+  const map = await admin.getJson<KubeObject & { data?: Record<string, string> }>({
+    kind: "configmap",
+    name: IMAGES_CONFIGMAP,
+    namespace,
+    ...ctx,
+  });
+  const raw = map?.data?.[IMAGES_KEY];
+  if (raw) {
+    try {
+      deployed.images = JSON.parse(raw) as Images;
+    } catch {
+      // an unreadable map is reported by its absence; the orchestrator line already carries the hash
+    }
+  }
+  return deployed;
+}
+
+/** The first container's image of a Deployment, read loosely — this is a report, not a contract. */
+function firstImage(obj?: KubeObject): string | undefined {
+  const spec = obj?.spec as { template?: { spec?: { containers?: Array<{ image?: string }> } } } | undefined;
+  return spec?.template?.spec?.containers?.[0]?.image;
+}
+
+function skew(report: VersionReport): Skew {
+  const local = report.kit?.version;
+  const remote = report.deployed?.orchestrator;
+  if (!local || !remote || "error" in remote || !remote.version) return "unknown";
+  const d = compareVersions(remote.version, local);
+  return d === 0 ? "same" : d < 0 ? "behind" : "ahead";
+}
+
+// --- rendering -----------------------------------------------------------------------------------
+
+/** One row of the table: a label and its value. A blank label is the gap between the halves. */
+type Row = [label: string, value: string];
+
+const copy = (c: Copy): string => `${c.version.padEnd(8)} ${c.path}`;
+
+/** The human table. Every row is one fact; the `skew` row is the only sentence. Labels are padded
+ * to the longest present, so a `sandbox <key>` row cannot crowd its value. */
+export function render(r: VersionReport): string {
+  const rows: Row[] = [["cli", copy(r.cli)]];
+  if (r.global) rows.push(["global", copy(r.global)]);
+  if (r.kit) rows.push(["kit", renderKit(r.kit)]);
+  if (r.instance) {
+    const i = r.instance;
+    const mode = i.mode === "checkout" ? `kit checkout at ${i.kitCheckout}` : `installed kit → ${i.kitRegistry}`;
+    rows.push(["instance", `${i.name}  ${i.root}  (${mode})`]);
+    if (i.configError) rows.push(["config", `failed to load — ${i.configError}`]);
+  } else {
+    rows.push(["instance", "none — no jr2.config.ts walking up from cwd"]);
+  }
+  rows.push(["node", r.node]);
+  if (r.deployed) rows.push(["", ""], ...deployedRows(r.deployed, r));
+  const width = Math.max(...rows.map(([label]) => label.length)) + 3;
+  return rows.map(([label, value]) => (label ? `${`${label}:`.padEnd(width)}${value}` : "")).join("\n") + "\n";
+}
+
+function renderKit(k: NonNullable<VersionReport["kit"]>): string {
+  const pinned = k.pinned !== undefined ? `; package.json pins ${k.pinned} — reinstall` : "";
+  if (k.check === "unresolved") return `not installed${pinned}`;
+  const head = copy({ version: k.version!, path: k.path! });
+  if (k.check === "ok") return `${head}  ok${pinned}`;
+  const against = k.against
+    ? `this jr2 runs against ${k.against.version} (${k.against.path})`
+    : "this jr2 has no @jr2/orchestrator beside it";
+  return `${head}  MISMATCH — ${against}${pinned}`;
+}
+
+function deployedRows(d: NonNullable<VersionReport["deployed"]>, r: VersionReport): Row[] {
+  const rows: Row[] = [];
+  const o = d.orchestrator;
+  if (!o) rows.push(["orchestrator", "not probed"]);
+  else if ("error" in o) rows.push(["orchestrator", o.error]);
+  else {
+    const parts = [o.version ?? "(no version reported)"];
+    if (o.hash) parts.push(`hash ${o.hash}`);
+    if (o.deploymentHash && o.hash && o.deploymentHash !== o.hash) {
+      parts.push(`(rollout incomplete: deployment records ${o.deploymentHash})`);
+    }
+    if (o.image) parts.push(o.image);
+    rows.push(["orchestrator", parts.join("  ")]);
+  }
+  if (d.operator) {
+    rows.push(["operator", `${d.operator.version ?? "(unlabeled)"}  ${d.operator.image ?? ""}`.trimEnd()]);
+  }
+  if (d.images) {
+    if (d.images.harness) rows.push(["harness", d.images.harness]);
+    if (d.images.adapter) rows.push(["adapter", d.images.adapter]);
+    for (const [key, ref] of Object.entries(d.images.sandbox ?? {})) rows.push([`sandbox ${key}`, ref]);
+  }
+  const verdict = skewSentence(r);
+  if (verdict) rows.push(["skew", verdict]);
+  return rows;
+}
+
+function skewSentence(r: VersionReport): string | undefined {
+  const local = r.kit?.version;
+  const o = r.deployed?.orchestrator;
+  const remote = o && !("error" in o) ? o.version : undefined;
+  switch (r.skew) {
+    case "behind":
+      return `deployed ${remote} predates this kit ${local} — \`jr2 up\` converges it`;
+    case "ahead":
+      return (
+        `deployed ${remote} is newer than this kit ${local} — \`jr2 up\` would roll the orchestrator back; ` +
+        "the operator is never downgraded"
+      );
+    case "same":
+      return r.instance?.mode === "checkout"
+        ? "same version; checkout builds are content-addressed — compare the hash against `jr2 up`'s line"
+        : undefined;
+    default:
+      return undefined;
+  }
+}

package/src/handoff.ts

@@ -10,13 +10,30 @@
 // API the global (the copy that cannot be updated once shipped) must honor forever. The local's own
 // preamble runs: its pinned erasure hook, whatever a future bin adds.
 //
+// Plus one env var (ADR-0056 as amended): the copy that hands off names itself in
+// `JR2_HANDOFF_FROM`, because "is my global out of date" is the one fact the local copy cannot
+// learn on its own, and `jr2 version` answers it from here. Nothing else reads it.
+//
 // Builtins only, like everything the launcher runs before it knows which `jr2` will run.
 
 import { spawn } from "node:child_process";
 import { join } from "node:path";
-import { CLI_ROOT, resolvePackage } from "./kit-version.ts";
+import { CLI_ROOT, CLI_VERSION, resolvePackage } from "./kit-version.ts";
 import { findRoot } from "./root.ts";
 
+/** `<version> <realpath>` of the copy that handed off — set on the child by {@link handoff}. */
+export const HANDOFF_ENV = "JR2_HANDOFF_FROM";
+
+/** The copy that handed off to this process, if one did and said so. A global that predates the
+ * variable hands off silently, which reads the same as no handoff at all — there is no third source. */
+export function handedOffFrom(env: Record<string, string | undefined>): { version: string; path: string } | undefined {
+  const raw = env[HANDOFF_ENV];
+  if (!raw) return undefined;
+  const sp = raw.indexOf(" ");
+  if (sp < 0) return undefined;
+  return { version: raw.slice(0, sp), path: raw.slice(sp + 1) };
+}
+
 /** The local binary to hand off to, or `undefined` when this copy is the one that runs. */
 export function handoffTarget(cwd: string, selfRoot: string = CLI_ROOT): string | undefined {
   const root = findRoot(cwd);
@@ -31,7 +48,10 @@ export function handoffTarget(cwd: string, selfRoot: string = CLI_ROOT): string
  * by signal re-raises that signal here, so the shell sees what it would have seen. */
 export function handoff(bin: string, argv: string[]): Promise<number> {
   return new Promise((resolve) => {
-    const child = spawn(process.execPath, [bin, ...argv], { stdio: "inherit" });
+    const child = spawn(process.execPath, [bin, ...argv], {
+      stdio: "inherit",
+      env: { ...process.env, [HANDOFF_ENV]: `${CLI_VERSION} ${CLI_ROOT}` },
+    });
     child.on("error", (err) => {
       process.stderr.write(`error: cannot run ${bin}: ${err.message}\n`);
       resolve(1);

package/src/index.ts

@@ -6,7 +6,7 @@ export { JR2Client } from "./client.ts";
 export type { RunStatus, RunFeedEvent, RunEvent, FetchLike } from "./client.ts";
 export type { Io } from "./output.ts";
 export { resolveRoot, resolveTarget } from "./instance.ts";
-export { assertKitVersion, resolvePackage, CLI_VERSION } from "./kit-version.ts";
+export { assertKitVersion, checkKitVersion, resolvePackage, CLI_VERSION } from "./kit-version.ts";
 export type { Target, TargetOptions } from "./instance.ts";
 export { kubectlKube } from "./kube.ts";
 export type { KubePort } from "./kube.ts";

package/src/kit-version.ts

@@ -59,6 +59,52 @@ export const CLI_VERSION = (JSON.parse(readFileSync(join(CLI_ROOT, "package.json
 const ORCHESTRATOR = "@jr2/orchestrator";
 const CLI = "@jr2/cli";
 
+/**
+ * The ADR-0056 question, answered rather than asserted: what the Instance at `root` resolves
+ * `@jr2/orchestrator` to, what this CLI resolves it to, and whether they are one copy. `ok` is the
+ * real-path identity, never a version compare. `jr2 version` prints this; every other Instance verb
+ * goes through {@link assertKitVersion}, which turns a not-ok answer into the refusal.
+ */
+export type KitCheck = {
+  /** The Instance's own resolution — its Kit version; absent when nothing resolves from `root`. */
+  instance?: ResolvedPackage;
+  /** This CLI's peer; absent for a global with no orchestrator beside it. */
+  own?: ResolvedPackage;
+  /** What the Instance's manifest PINS for `@jr2/orchestrator`, verbatim — so "edited the line,
+   * never reinstalled" is visible as a pin that disagrees with what resolves. */
+  pinned?: string;
+  ok: boolean;
+};
+
+export function checkKitVersion(root: string): KitCheck {
+  const instance = resolvePackage(ORCHESTRATOR, root);
+  const own = resolvePackage(ORCHESTRATOR, CLI_ROOT);
+  return {
+    instance,
+    own,
+    pinned: pinnedVersion(root, ORCHESTRATOR),
+    ok: instance !== undefined && own !== undefined && instance.root === own.root,
+  };
+}
+
+/** The version `root/package.json` pins for `name`, from any dependency block; `undefined` when
+ * there is no manifest or no such line. The pin as WRITTEN — a range stays a range. */
+export function pinnedVersion(root: string, name: string): string | undefined {
+  try {
+    const m = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as Record<
+      string,
+      Record<string, string> | undefined
+    >;
+    for (const block of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+      const pin = m[block]?.[name];
+      if (pin !== undefined) return pin;
+    }
+  } catch {
+    // no manifest, or not JSON — the Instance has no pin to speak of
+  }
+  return undefined;
+}
+
 /**
  * Refuse unless the Instance at `root` and this CLI resolve the SAME `@jr2/orchestrator`. The
  * message names both versions and the lines to edit: an Instance with no `@jr2/cli` of its own is
@@ -66,9 +112,8 @@ const CLI = "@jr2/cli";
  * at one number.
  */
 export function assertKitVersion(root: string): void {
-  const instance = resolvePackage(ORCHESTRATOR, root);
-  const own = resolvePackage(ORCHESTRATOR, CLI_ROOT);
-  if (instance && own && instance.root === own.root) return;
+  const { instance, own, ok } = checkKitVersion(root);
+  if (ok) return;
 
   const manifest = join(root, "package.json");
   const local = instance && resolvePackage(CLI, root);