@jr2/cli 0.1.2 → 0.1.4

package/README.md

@@ -15,4 +15,9 @@ jr2 run <workflow>
 Orchestrator, Sandboxes, secrets), and every other verb (`run`, `runs`, `status`, `logs`, `send`, `down`, `gc`,
 `kit push`) talks to what `up` deployed. Node 24, a kube context, and docker for the image `up` builds.
 
+Inside an Instance, the global `jr2` hands off to the Instance's own `@jr2/cli` (the gulp model), so the version that
+runs is the one the Instance pins and the global's stops mattering. An Instance has one kit version: `@jr2/cli` and
+`@jr2/orchestrator` at the same exact number — every verb refuses a mismatch by name. Upgrade by editing both lines and
+reinstalling.
+
 Docs, glossary, and architecture decisions: [github.com/snapwich/jr2](https://github.com/snapwich/jr2).

package/bin/jr2.js

@@ -9,8 +9,12 @@
 // bundle solves the same problem with `tsx` (see INSTANCE_DOCKERFILE) because there the entry is
 // the orchestrator's, not this one.
 //
-// After the hook it does nothing but hand argv to `main` and surface the exit code. `main` is
-// pure-ish (takes an injectable IO) so the dispatch + commands stay unit-testable without a process.
+// After the hook, the launcher's one decision (ADR-0056): inside an Instance that resolves its own
+// `@jr2/cli` to a different copy, hand off — run THAT copy's binary with the same argv and stdio
+// and exit with its code — so the `jr2` that runs is the one the Instance pins, whatever this one's
+// version is. Otherwise hand argv to `main` and surface the exit code. `main` is pure-ish (takes an
+// injectable IO) so the dispatch + commands stay unit-testable without a process. The handoff
+// modules import no kit code: a global with no orchestrator beside it can still hand off.
 
 import { readFileSync } from "node:fs";
 import { registerHooks } from "node:module";
@@ -31,8 +35,12 @@ registerHooks({
   },
 });
 
-const { main } = await import("../src/cli.ts");
-
-main(process.argv.slice(2)).then((code) => {
-  process.exitCode = code;
-});
+const argv = process.argv.slice(2);
+const { handoffTarget, handoff } = await import("../src/handoff.ts");
+const local = handoffTarget(process.cwd());
+if (local) {
+  process.exitCode = await handoff(local, argv);
+} else {
+  const { main } = await import("../src/cli.ts");
+  process.exitCode = await main(argv);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "The jr2 CLI: init, up, run — the interface to a jr2 Instance.",
   "license": "MIT",
   "private": false,
@@ -36,13 +36,16 @@
   },
   "types": "./src/index.ts",
   "dependencies": {
-    "ts-blank-space": "^0.9.0",
-    "@jr2/orchestrator": "0.1.2"
+    "ts-blank-space": "^0.9.0"
+  },
+  "peerDependencies": {
+    "@jr2/orchestrator": "0.1.4"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
     "xstate": "^5.18.0",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@jr2/orchestrator": "0.1.4"
   },
   "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/init.ts

@@ -13,19 +13,22 @@
 // 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
+// carries the 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`.
+// @jr2/* at the exact running version: 0.x minors break, and the checkout resolves that literal
+// to its own packages via `linkWorkspacePackages: true`. The number is the CLI's OWN (ADR-0056),
+// not the orchestrator's `KIT_VERSION`: a global `jr2` with no Instance around it must scaffold
+// without a peer resolved, and the two numbers are equal by construction (one release train,
+// lockstep — ADR-0055).
 
 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 { CLI_VERSION } from "../kit-version.ts";
 import { activity, type Io } from "../output.ts";
 
 export async function init(args: string[], io: Io): Promise<number> {
@@ -90,8 +93,8 @@ function packageJson(name: string): string {
       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" },
+      dependencies: { "@jr2/orchestrator": CLI_VERSION, xstate: "^5.18.0" },
+      devDependencies: { "@jr2/cli": CLI_VERSION, "@types/node": "^26.0.1", typescript: "^5.6.0" },
     },
     null,
     2,

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/env.ts

@@ -16,7 +16,7 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { findRoot } from "./instance.ts";
+import { findRoot } from "./root.ts";
 import { activity, type Io } from "./output.ts";
 
 /**

package/src/handoff.ts

@@ -0,0 +1,64 @@
+// The Handoff (ADR-0056, the gulp/grunt model): a global `jr2` run inside an Instance that resolves
+// its own `@jr2/cli` to a DIFFERENT copy runs that copy's binary with the same arguments and stdio,
+// returns its exit code, and does nothing else. So the copy that runs is the one the Instance pins,
+// and the global's version stops mattering inside an Instance. No Instance, or the Instance resolves
+// the running copy itself (a workspace member in the checkout, `npx jr2`): no handoff.
+//
+// Spawn, not import. gulp loads local gulp in-process because local gulp is a LIBRARY; here the
+// local is a BINARY, and spawning couples the global to one contract — the package's `bin` field,
+// npm's own — where importing `src/cli.ts` would make the local's internal layout a cross-version
+// 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, 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);
+  if (!root) return undefined;
+  const local = resolvePackage("@jr2/cli", root);
+  if (!local || local.root === selfRoot) return undefined;
+  const bin = typeof local.bin === "string" ? local.bin : local.bin?.jr2;
+  return bin ? join(local.root, bin) : undefined;
+}
+
+/** Run `bin` with `argv` on this node, sharing stdio; resolves to its exit code. A child that dies
+ * 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",
+      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);
+    });
+    child.on("exit", (code, signal) => {
+      if (signal) process.kill(process.pid, signal);
+      resolve(code ?? 1);
+    });
+  });
+}

package/src/index.ts

@@ -6,6 +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, 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/instance.ts

@@ -2,7 +2,9 @@
 // folder we are in, and WHERE its deployed orchestrator is.
 //
 //   - `resolveRoot` walks up from cwd to the dir holding `jr2.config.ts` — the root marker (mirrors
-//     flue's `flue.config.ts`).
+//     flue's `flue.config.ts`) — and refuses unless that Instance and this CLI resolve the same
+//     `@jr2/orchestrator` (ADR-0056: an Instance has one Kit version). Every Instance verb goes
+//     through it; `--url` verbs skip the walk and so skip the check.
 //   - `resolveTarget` finds the orchestrator. `--url` / `JR2_URL` (+ `JR2_TOKEN`) short-circuits
 //     everything — the ingress-exposed/remote-caller escape hatch, no folder walk. Otherwise the
 //     DEPLOYMENT is addressed by the current kube context + the instance's namespace (`-n` >
@@ -11,27 +13,21 @@
 //     kube RBAC is the real gate, and no local state file can go stale (ADR-0019).
 //   - Every resolution prints its target on stderr, so ambient-context drift stays visible.
 
-import { existsSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename } from "node:path";
 import { loadConfig } from "@jr2/orchestrator";
 import { INSTANCE_SECRET, kubectlKube, ORCHESTRATOR_PORT, ORCHESTRATOR_SERVICE } from "./kube.ts";
+import { assertKitVersion } from "./kit-version.ts";
 import { activity, type Io } from "./output.ts";
+import { findRoot } from "./root.ts";
 
-/** Walk up from `cwd` to the directory containing `jr2.config.ts`; `undefined` if there is none. */
-export function findRoot(cwd: string): string | undefined {
-  let dir = cwd;
-  for (;;) {
-    if (existsSync(join(dir, "jr2.config.ts"))) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) return undefined;
-    dir = parent;
-  }
-}
+export { findRoot } from "./root.ts";
 
-/** `findRoot`, for the callers that cannot proceed without one. */
+/** `findRoot` for the callers that cannot proceed without one — and the Kit version check, which
+ * every Instance verb therefore makes before it reads a byte of the Instance. */
 export function resolveRoot(cwd: string): string {
   const root = findRoot(cwd);
   if (!root) throw new Error("not inside a jr2 instance — no jr2.config.ts found walking up from cwd");
+  assertKitVersion(root);
   return root;
 }
 

package/src/kit-version.ts

@@ -0,0 +1,133 @@
+// An Instance has ONE Kit version (ADR-0056): the `@jr2/orchestrator` it resolves, because that is
+// what its image bakes. Published `@jr2/cli@X` used to DEPEND on `@jr2/orchestrator@X` exact, so an
+// Instance pinning any other orchestrator quietly held two copies — the CLI's `KIT_VERSION` named
+// one, the bundle baked the other, and the CLI's own code handled config objects built by a
+// different copy of the same classes. Now the orchestrator is the CLI's PEER (one copy can exist),
+// and every Instance verb asks this module whether the copy the CLI resolves IS the copy the
+// Instance resolves: same REAL path, never a version compare. Same file means same version by
+// construction under npm hoisting, pnpm dedup, and checkout symlinks alike — and identity is
+// exactly the property the class-identity bug needs.
+//
+// Builtins only: the launcher (`bin/jr2.js`) resolves through here before any kit import.
+
+import { readFileSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type ResolvedPackage = {
+  /** The package's REAL root directory (symlinks resolved). */
+  root: string;
+  version: string;
+  bin?: string | Record<string, string>;
+};
+
+/**
+ * Resolve `name` the way code in `fromDir` would — Node resolution from that folder — and answer
+ * the package's real root. `undefined` when nothing resolves (no `node_modules` yet, or a global
+ * with no peer beside it). Walks up from the resolved ENTRY to the nearest manifest carrying the
+ * name, rather than resolving `<name>/package.json`, because an `exports` map hides the manifest
+ * and the kits already published export none.
+ */
+export function resolvePackage(name: string, fromDir: string): ResolvedPackage | undefined {
+  const require = createRequire(join(fromDir, "package.json"));
+  let entry: string;
+  try {
+    entry = realpathSync(require.resolve(name));
+  } catch {
+    return undefined;
+  }
+  let dir = dirname(entry);
+  for (;;) {
+    try {
+      const m = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as ResolvedPackage & { name?: string };
+      if (m.name === name) return { root: dir, version: m.version, bin: m.bin };
+    } catch {
+      // not a manifest, or not this package's — keep walking
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/** This CLI's own real root and version — what `jr2 init` pins (ADR-0056), what the refusal names. */
+export const CLI_ROOT = realpathSync(fileURLToPath(new URL("..", import.meta.url)));
+export const CLI_VERSION = (JSON.parse(readFileSync(join(CLI_ROOT, "package.json"), "utf8")) as { version: string })
+  .version;
+
+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
+ * told to add one (the launcher then hands off to it); one that has it is told to pin both lines
+ * at one number.
+ */
+export function assertKitVersion(root: string): void {
+  const { instance, own, ok } = checkKitVersion(root);
+  if (ok) return;
+
+  const manifest = join(root, "package.json");
+  const local = instance && resolvePackage(CLI, root);
+  const fix = !instance
+    ? `install the Instance's dependencies (${manifest} pins "${ORCHESTRATOR}" and "${CLI}" at one exact version)`
+    : local
+      ? `pin "${ORCHESTRATOR}" and "${CLI}" at ONE exact version in ${manifest} and reinstall`
+      : `add "${CLI}": "${instance.version}" to devDependencies in ${manifest} and reinstall — the Instance's ` +
+        `own jr2 then runs`;
+  const have = instance
+    ? `${ORCHESTRATOR} resolves to ${instance.version} (${instance.root})`
+    : `${ORCHESTRATOR} does not resolve from ${root}`;
+  const self = own
+    ? `this jr2 (${CLI_VERSION}) runs against ${own.version} (${own.root})`
+    : `this jr2 (${CLI_VERSION}, at ${CLI_ROOT}) has no ${ORCHESTRATOR} beside it`;
+  throw new Error(`Kit version mismatch — an Instance has one (ADR-0056):\n  ${have}\n  ${self}\n  ${fix}`);
+}

package/src/root.ts

@@ -0,0 +1,17 @@
+// The Instance root walk (ADR-0009): up from `cwd` to the directory holding `jr2.config.ts`, the
+// root marker. Its own module — builtins only — because the launcher runs it BEFORE it knows which
+// `jr2` will run (ADR-0056), so nothing here may import the kit.
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Walk up from `cwd` to the directory containing `jr2.config.ts`; `undefined` if there is none. */
+export function findRoot(cwd: string): string | undefined {
+  let dir = cwd;
+  for (;;) {
+    if (existsSync(join(dir, "jr2.config.ts"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}