@jr2/cli 0.6.0 → 0.7.0

package/src/deploy.ts

@@ -3,10 +3,15 @@
 // namespace are constants (namespace is the identity); every object carries the instance label so
 // ownership is derivable from the cluster — there is no local target state.
 
-import { createHmac, randomBytes } from "node:crypto";
+import { createHash, createHmac, randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import {
+  CALLER_DIGESTS_KEY,
+  CALLER_DIGESTS_MOUNT,
+  CALLER_DIGESTS_SECRET,
+  callerTokenDigest,
+  callerTokenSecret,
   CA_CONFIGMAP,
   CA_MOUNT,
   EFFECTOR_PORT,
@@ -24,6 +29,9 @@ import {
   controlToken,
   heldStandIn,
   heldStandInKey,
+  HOOK_DIGESTS_KEY,
+  HOOK_DIGESTS_MOUNT,
+  HOOK_DIGESTS_SECRET,
   INSTANCE_CUSTODIAN_CONFIGMAP,
   GIT_SSH_SECRET,
   HELD_CA_SECRET,
@@ -52,6 +60,8 @@ import {
   REPO_CACHE_HOSTPATH,
   SERVICE_ACCOUNT_CA,
   STATE_PVC,
+  STATE_VOLUME_DEFAULT,
+  memoryBytes,
   type EffectorPlan,
   type SandboxEffectorPlan,
   effectorManifestKey,
@@ -64,6 +74,9 @@ import {
   type GitCloneSecret,
   type GitPushManifest,
   type HarnessConfig,
+  type JR2Config,
+  isStdioServer,
+  mcpTimeoutMs,
   type HeldManifest,
   markHarnessEnv,
   type PriorityClasses,
@@ -92,9 +105,85 @@ export const ANNOTATION_IMAGES = "jr2.dev/images";
 
 export const ORCHESTRATOR_SA = "jr2-orchestrator";
 
+/** The label on each named Caller token's Secret (ADR-0078), with the token's name as its value.
+ * `jr2 up` finds the Secrets of the names that the config no longer declares by it, and
+ * `jr2 caller rotate` finds every value whose digest the Orchestrator reads. */
+export const LABEL_CALLER_TOKEN = "jr2.dev/caller-token";
+
+/** The key of a named Caller token's value in its Secret (`callerTokenSecret`). */
+export const CALLER_TOKEN_KEY = "token";
+
+/**
+ * The `jr2-caller-digests` file (ADR-0078): one JSON object from each named Caller token's name to
+ * the sha-256 of its value, in hex, names in order. The Orchestrator reads it through a mount, and
+ * never a value.
+ */
+export function callerDigestsJson(values: Readonly<Record<string, string>>): string {
+  const names = Object.keys(values).sort();
+  return JSON.stringify(Object.fromEntries(names.map((n) => [n, callerTokenDigest(values[n]!)])));
+}
+
+/**
+ * The Secrets of the named Caller tokens (ADR-0078): one per name, which holds its value and which
+ * no pod mounts (`jr2 caller token` reads it over the kube API), and `jr2-caller-digests`, which
+ * the Orchestrator mounts. The digests Secret is applied always, empty with no token, so the
+ * mount always has its Secret.
+ */
+export function callerTokenObjects(
+  values: Readonly<Record<string, string>>,
+  meta: (name: string, extra?: Record<string, string>) => KubeManifest,
+): KubeManifest[] {
+  return [
+    ...Object.keys(values)
+      .sort()
+      .map(
+        (name): KubeManifest => ({
+          apiVersion: "v1",
+          kind: "Secret",
+          metadata: meta(callerTokenSecret(name), { [LABEL_CALLER_TOKEN]: name }),
+          type: "Opaque",
+          stringData: { [CALLER_TOKEN_KEY]: values[name]! },
+        }),
+      ),
+    {
+      apiVersion: "v1",
+      kind: "Secret",
+      metadata: meta(CALLER_DIGESTS_SECRET),
+      type: "Opaque",
+      stringData: { [CALLER_DIGESTS_KEY]: callerDigestsJson(values) },
+    },
+  ];
+}
+
+/**
+ * `jr2-hook-digests` (ADR-0078): one JSON object from the secret name of each Hook whose verifier is
+ * `token` to the sha-256 of its value, in hex, names in order. The Orchestrator mounts it, reads it
+ * again when it changes, and never holds a value. Applied always, empty with no `token` Hook, so the
+ * mount always has its Secret.
+ */
+export function hookDigestsObject(
+  digests: Readonly<Record<string, string>>,
+  meta: (name: string) => KubeManifest,
+): KubeManifest {
+  const names = Object.keys(digests).sort();
+  return {
+    apiVersion: "v1",
+    kind: "Secret",
+    metadata: meta(HOOK_DIGESTS_SECRET),
+    type: "Opaque",
+    stringData: { [HOOK_DIGESTS_KEY]: JSON.stringify(Object.fromEntries(names.map((n) => [n, digests[n]!]))) },
+  };
+}
+
 /** The HMAC over the held-secret inputs, on the Instance Harness's pod template (ADR-0059). */
 export const ANNOTATION_HELD_DIGEST = "jr2.dev/held-digest";
 
+/** The digest of the `jr2-harness` ConfigMap's text (`harnessConfigJson`), on the Instance
+ * Harness's pod template: the Harness reads the text once, at start, so an edit to the custom
+ * provider, a gateway or an MCP server (ADR-0079) rolls the pod. The text holds no value, so the
+ * digest is not keyed. */
+export const ANNOTATION_HARNESS_CONFIG_DIGEST = "jr2.dev/harness-config-digest";
+
 /** The Instance Harness pod's `fsGroup` — a Sandbox pod's default work group (ADR-0005), for the
  * same reason: a group every container is granted, which the Custodian's values are readable by. */
 const INSTANCE_HARNESS_FS_GROUP = 2000;
@@ -346,21 +435,77 @@ export type HeldObjects = {
 /** Does any pod hold a secret? */
 export const holdsAny = (held: HeldObjects): boolean => held.pods.some((p) => p.manifest.secrets.length > 0);
 
+/** What `jr2 up` does with the state volume claim (ADR-0065): the size to apply and the one line
+ * that says what changed, or the refusal's text. */
+export type StateVolumePlan = { size: string; line?: string } | { refused: string };
+
+/**
+ * The size of the Orchestrator's state volume claim (ADR-0065). `configured` is `runs.volume`;
+ * `claim` the claim that exists, with its StorageClass and whether the class allows expansion
+ * (`undefined` when `jr2 up` did not read it). A new claim takes `runs.volume` or the default. A
+ * claim that exists keeps its size when the config sets none, grows when the config sets a larger
+ * size on a class that expands, and refuses a smaller size, or a larger one on a class that does
+ * not expand: Kubernetes never makes a claim smaller, and grows it only where the class allows.
+ */
+export function stateVolumePlan(
+  configured: string | undefined,
+  claim?: { size: string; storageClass?: string; expandable?: boolean },
+): StateVolumePlan {
+  if (!claim) return { size: configured ?? STATE_VOLUME_DEFAULT };
+  if (configured === undefined) {
+    if (memoryBytes(claim.size) === memoryBytes(STATE_VOLUME_DEFAULT)) return { size: claim.size };
+    return {
+      size: claim.size,
+      line: `state volume: keeping the claim ${STATE_PVC} at ${claim.size} — runs.volume is not set, and the default ${STATE_VOLUME_DEFAULT} is for a new claim`,
+    };
+  }
+  const want = memoryBytes(configured);
+  const have = memoryBytes(claim.size);
+  if (want === have) return { size: claim.size };
+  if (want < have) {
+    return {
+      refused:
+        `runs.volume is ${configured}, smaller than the state volume claim ${STATE_PVC} (${claim.size}) — Kubernetes never ` +
+        `makes a claim smaller. Set runs.volume to ${claim.size} or more (ADR-0065)`,
+    };
+  }
+  const named = claim.storageClass ? `StorageClass "${claim.storageClass}"` : "claim's StorageClass";
+  if (claim.expandable !== true) {
+    return {
+      refused:
+        `runs.volume is ${configured}, larger than the state volume claim ${STATE_PVC} (${claim.size}), and its ${named} ` +
+        `does not allow expansion (allowVolumeExpansion is not true). Keep runs.volume at ${claim.size}, or use a ` +
+        `StorageClass that allows expansion (ADR-0065)`,
+    };
+  }
+  return { size: configured, line: `state volume: growing the claim ${STATE_PVC} from ${claim.size} to ${configured}` };
+}
+
 /** Everything `jr2 up` converges inside the instance's namespace, as one apply-able List. */
 export function instanceObjects(opts: {
   name: string;
   namespace: string;
+  /** The size of the state volume claim (`stateVolumePlan`, ADR-0065). Default: `5Gi`. */
+  stateVolume?: string;
   /** The Orchestrator Kit image's ref (ADR-0069). The Deployment carries no content hash: the
    * Assembly's hash is an Orchestrator fact, read from `GET /assembly`. */
   image: string;
   /** Secret data (the Instance token, the publish token, the signing key) — written stringData,
    * kube encodes. The Orchestrator reads it through `envFrom`. */
   secretData: Record<string, string>;
+  /** The values of the named Caller tokens, by name (ADR-0078): each goes into a Secret of its own,
+   * and the Orchestrator mounts only their digests (`callerTokenObjects`). Absent: none. */
+  callerTokens?: Readonly<Record<string, string>>;
+  /** The sha-256 digests of the `token` Hooks' secrets, by secret name (ADR-0078): the Orchestrator
+   * mounts them in `jr2-hook-digests` (`hookDigestsObject`). Absent: none. */
+  hookDigests?: Readonly<Record<string, string>>;
   /** The HARNESS containers' literal `harness.env` values — a SEPARATE Secret from `secretData` by
    * doctrine (ADR-0013): Agent code executes where this lands, so the Instance token and signing
    * key must never share a Secret with it, and no model key rides it either (ADR-0059). */
   harnessEnvData: Record<string, string>;
   harness?: HarnessConfig;
+  /** The config's `mcp` block (ADR-0079), for the `jr2-harness` ConfigMap. */
+  mcp?: JR2Config["mcp"];
   /** Held secrets (ADR-0059): the Custodian's objects. The `jr2-held` ConfigMap is applied always —
    * every Harness pod runs a Custodian — and the rest only while a secret is held. */
   held: HeldObjects;
@@ -404,7 +549,7 @@ export function instanceObjects(opts: {
       metadata: meta(STATE_PVC),
       spec: {
         accessModes: ["ReadWriteOnce"],
-        resources: { requests: { storage: "1Gi" } },
+        resources: { requests: { storage: opts.stateVolume ?? STATE_VOLUME_DEFAULT } },
       },
     },
     { apiVersion: "v1", kind: "ServiceAccount", metadata: meta(ORCHESTRATOR_SA) },
@@ -449,7 +594,7 @@ export function instanceObjects(opts: {
       kind: "ConfigMap",
       metadata: meta(HARNESS_CONFIGMAP),
       data: {
-        [HARNESS_CONFIG_KEY]: harnessConfigJson(opts.harness),
+        [HARNESS_CONFIG_KEY]: harnessConfigJson(opts.harness, opts.mcp),
       },
     },
     {
@@ -541,6 +686,13 @@ export function instanceObjects(opts: {
       type: "Opaque",
       stringData: opts.secretData,
     },
+    // The named Caller tokens (ADR-0078): a value in a Secret of its own, and the digests in the
+    // one Secret the Orchestrator mounts below. Not in `jr2-instance`: that one is `envFrom`, which
+    // a running pod reads once, and a new token or a rotation must roll no pod.
+    ...callerTokenObjects(opts.callerTokens ?? {}, meta),
+    // The `token` Hooks' digests (ADR-0078): a Secret of their own, as the door reads them, and
+    // never `jr2-caller-digests`, which `jr2 caller rotate` writes whole. Never a value.
+    hookDigestsObject(opts.hookDigests ?? {}, meta),
     {
       // What the HARNESS containers envFrom (see `harnessEnvData` above): Agent creds, never the
       // Instance token. Always applied (possibly empty) so the Sandbox spec can reference it
@@ -594,6 +746,9 @@ export function instanceObjects(opts: {
                   // built-in `fetch`, which trusts the ServiceAccount's CA through this and nothing
                   // else — no TLS code, no dependency.
                   { name: "NODE_EXTRA_CA_CERTS", value: SERVICE_ACCOUNT_CA },
+                  // The claim's size as this converge applied it (ADR-0065): the space guard
+                  // measures against it, because a hostPath class's `statfs` gives the node's disk.
+                  { name: "JR2_STATE_VOLUME", value: opts.stateVolume ?? STATE_VOLUME_DEFAULT },
                 ],
                 // The Orchestrator creates Repo resources and never clones (ADR-0051) — the cache
                 // agent on each node does, reading the credential Secret a Repo's `secretRef`
@@ -608,6 +763,13 @@ export function instanceObjects(opts: {
                   // (ADR-0059): names and hosts, which this process could not derive — its `.env`
                   // values are absent.
                   { name: "held", mountPath: HELD_MOUNT, readOnly: true },
+                  // The digests of the named Caller tokens (ADR-0078), read again when they
+                  // change: a new token or a rotation costs one kubelet propagation window, about
+                  // a minute, and no rollout. Never a value.
+                  { name: "callers", mountPath: CALLER_DIGESTS_MOUNT, readOnly: true },
+                  // The digests of the `token` Hooks' secrets (ADR-0078), read again in the same
+                  // way: a new or changed secret costs one kubelet propagation window. Never a value.
+                  { name: "hooks", mountPath: HOOK_DIGESTS_MOUNT, readOnly: true },
                 ],
                 resources: sized(KIT_POD_SIZES.orchestrator),
                 // The period, not the boot, is what `up`'s rollout wait measures. Measured: the
@@ -645,6 +807,8 @@ export function instanceObjects(opts: {
               { name: "state", persistentVolumeClaim: { claimName: STATE_PVC } },
               { name: "images", configMap: { name: IMAGES_CONFIGMAP } },
               { name: "held", configMap: { name: HELD_CONFIGMAP } },
+              { name: "callers", secret: { secretName: CALLER_DIGESTS_SECRET } },
+              { name: "hooks", secret: { secretName: HOOK_DIGESTS_SECRET } },
             ],
           },
         },
@@ -955,7 +1119,8 @@ export function instanceHarnessObjects(opts: {
    * Agent cannot execute code — forking the path for one pod buys a divergence ADR-0031 declines. */
   custodianImage: string;
   /** What this converge placed in the Instance Harness (ADR-0059): its own manifest — the model
-   * keys its `"none"` Agents' providers read, and nothing else. */
+   * keys its `"none"` Agents' providers read and the secrets of the remote MCP servers they name
+   * (ADR-0079), and nothing else. */
   held: HeldManifest;
   /** Its Custodian's two files, rendered from `held` — applied here, with the pod they are for
    * (`INSTANCE_CUSTODIAN_CONFIGMAP`, ADR-0059). */
@@ -968,6 +1133,9 @@ export function instanceHarnessObjects(opts: {
    * Stand-ins, applied here as {@link INSTANCE_HARNESS_CREDENTIALS} with the pod they are for. */
   credentials: Record<string, string>;
   harness?: HarnessConfig;
+  /** The config's `mcp` block (ADR-0079): with `harness`, the text of the `jr2-harness` ConfigMap,
+   * whose digest is on the pod template. */
+  mcp?: JR2Config["mcp"];
   /** The instance ships a private-CA bundle (ADR-0020). */
   caBundle?: boolean;
   /** The digest of this placement's Harness bearer (ADR-0058; `harnessTokenDigest(key,
@@ -1109,7 +1277,16 @@ export function instanceHarnessObjects(opts: {
             // start (ADR-0059, the ADR-0037 stance). A move costs a drain, not the conversations
             // (the volume keeps them), yet no autoscaler may choose one (ADR-0060) — a drain still
             // can.
-            annotations: { [ANNOTATION_HELD_DIGEST]: opts.heldDigest, ...NO_DISRUPT_ANNOTATIONS },
+            // The same for the `jr2-harness` text, which the Harness reads once at start: a server
+            // added to `mcp`, or a url, an argv or a timeout changed, reaches the pod (ADR-0079).
+            annotations: {
+              [ANNOTATION_HELD_DIGEST]: opts.heldDigest,
+              [ANNOTATION_HARNESS_CONFIG_DIGEST]: createHash("sha256")
+                .update(harnessConfigJson(opts.harness, opts.mcp))
+                .digest("base64url")
+                .slice(0, 32),
+              ...NO_DISRUPT_ANNOTATIONS,
+            },
           },
           spec: {
             // The drain (ADR-0031): on SIGTERM the Harness stops admitting and finishes the Turns
@@ -1171,9 +1348,10 @@ export function instanceHarnessObjects(opts: {
 }
 
 /** What the Instance can REACH (ADR-0018), as the `jr2-harness` ConfigMap carries it to every
- * Harness container: the custom provider without its key and the catalog gateways. The check pod
- * carries the same text in its own ConfigMap (ADR-0019). */
-export function harnessConfigJson(harness: HarnessConfig | undefined): string {
+ * Harness container: the custom provider without its key, the catalog gateways, and the MCP servers
+ * (ADR-0079) — a remote one's url and the NAME of its secret, never a value. The check pod carries
+ * the same text in its own ConfigMap (ADR-0019). */
+export function harnessConfigJson(harness: HarnessConfig | undefined, mcp?: JR2Config["mcp"]): string {
   return JSON.stringify(
     {
       // apiKey is deliberately dropped: it is a held secret (ADR-0059) — the Custodian holds
@@ -1192,12 +1370,35 @@ export function harnessConfigJson(harness: HarnessConfig | undefined): string {
         : undefined,
       // Where pi's catalog providers send their calls (ADR-0059): endpoints, not keys.
       catalog: harness?.catalog,
+      // The MCP servers (ADR-0079), by the config's name: the Harness joins each Agent's `mcp` list
+      // to them. In-cluster the config has no `.env`, so the url rides from here, as baseUrl does.
+      mcp: mcp === undefined ? undefined : mcpSpecOf(mcp),
     },
     null,
     2,
   );
 }
 
+/** The `mcp` block as the Harness reads it (`McpServerSpec` in `@jr2/harness`): the timeout in
+ * milliseconds, and a stdio server's `args` always a list. */
+function mcpSpecOf(mcp: NonNullable<JR2Config["mcp"]>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(mcp).map(([name, server]) => {
+      const timeoutMs = mcpTimeoutMs(server.timeout);
+      return [
+        name,
+        isStdioServer(server)
+          ? { command: server.command, args: [...(server.args ?? [])], timeoutMs }
+          : { url: server.url, ...(server.secret !== undefined ? { secret: server.secret } : {}), timeoutMs },
+      ];
+    }),
+  );
+}
+
+/** The argv word of `provider-preflight.ts` before the MCP servers to list (`PREFLIGHT_MCP_ARG` in
+ * `@jr2/harness`'s `preflight-line.ts`, which a test holds this to). */
+export const PREFLIGHT_MCP_ARG = "--mcp";
+
 /** The provider preflight's objects (ADR-0019): a check pod and its own copies of what it reads,
  * each named `jr2-provider-preflight-<run>-<n>` or that name and a suffix, unique to one `jr2 up`. */
 export const PROVIDER_PREFLIGHT = "jr2-provider-preflight";
@@ -1275,6 +1476,11 @@ export function checkPodObjects(opts: {
   harnessEnvData: Record<string, string>;
   /** The `<provider>/<model>` specifiers to check, in order. */
   models: readonly string[];
+  /** The remote MCP servers whose tools to list, by the config's name, in order (ADR-0079). */
+  servers?: readonly string[];
+  /** The config's `mcp` block: the check pod's harness config carries it, as the Harness pods'
+   * does, so the check reads each server's url and secret name where a Turn reads them. */
+  mcp?: JR2Config["mcp"];
   /** The node predicate of the Harness pods this check pod stands for. */
   placement?: SandboxPlacement;
   priorityClassName: string;
@@ -1337,6 +1543,7 @@ export function checkPodObjects(opts: {
             "/opt/jr2/bin/node",
             "/opt/jr2/src/provider-preflight.ts",
             ...opts.models,
+            ...(opts.servers?.length ? [PREFLIGHT_MCP_ARG, ...opts.servers] : []),
           ],
           // The Harness container's env, in its order (`instanceHarnessObjects`): no credential. And
           // the check pod's own Stand-ins (ADR-0019): it runs no Workspace code, so it may hold them
@@ -1390,7 +1597,7 @@ export function checkPodObjects(opts: {
         [CUSTODIAN_BOOTSTRAP_KEY]: opts.custodian.bootstrap,
         [CUSTODIAN_SCRIPT_KEY]: opts.custodian.script,
         [CUSTODIAN_PROGRAM_KEY]: CUSTODIAN_PROGRAM,
-        [HARNESS_CONFIG_KEY]: harnessConfigJson(opts.harness),
+        [HARNESS_CONFIG_KEY]: harnessConfigJson(opts.harness, opts.mcp),
       },
     },
     { apiVersion: "v1", kind: "ConfigMap", metadata: meta(`${o}-ca`), data: opts.trust },
@@ -1453,7 +1660,8 @@ export const effectorGraceSeconds = (plan: EffectorPlan): number =>
 
 /**
  * The Instance Effector (ADR-0068): the objects `jr2 up` converges when a registered Machine
- * places an Effect there — an `http` Effect — and deletes otherwise.
+ * places an Effect there — an `http` Effect — or a Hook needs it (a `mac` verifier, or a kind that
+ * declares `posts`), and deletes otherwise.
  *
  * - A Deployment, not a StatefulSet: a rollout must run the new pod beside the old one (surge), so
  *   the old one finishes an Effect in flight while the new one takes new Effects. The Kit's
@@ -1504,7 +1712,13 @@ export function instanceEffectorObjects(opts: {
         : [],
     ),
   ];
-  const config = { version: 1, placement: opts.plan.placement, targets: opts.plan.targets };
+  // The servers its `mcp` Effects call (ADR-0079): each one's url, its secret's name, its timeout.
+  const config = {
+    version: 1,
+    placement: opts.plan.placement,
+    targets: opts.plan.targets,
+    ...(Object.keys(opts.plan.mcp).length ? { mcp: opts.plan.mcp } : {}),
+  };
 
   const container = {
     name: "effector",
@@ -1644,7 +1858,14 @@ export type ValueDigest = (secret: string, key: string) => string | undefined;
  * annotation reveals nothing about a value. */
 export function effectorDigest(signingKey: Buffer, plan: EffectorPlan, key: string, valueDigest: ValueDigest): string {
   const mac = createHmac("sha256", signingKey);
-  mac.update(JSON.stringify({ secrets: plan.secrets, targets: plan.targets, longest: plan.longestTimeoutMs }));
+  mac.update(
+    JSON.stringify({
+      secrets: plan.secrets,
+      targets: plan.targets,
+      longest: plan.longestTimeoutMs,
+      ...(Object.keys(plan.mcp).length ? { mcp: plan.mcp } : {}),
+    }),
+  );
   for (const name of Object.keys(plan.values).sort()) mac.update(`${name}=${plan.values[name]}`);
   for (const s of plan.secrets) {
     if (s.source.kind === "secret") mac.update(`${s.name}<-${valueDigest(s.source.secret, s.source.key) ?? ""}`);

package/src/instance-check.ts

@@ -18,9 +18,15 @@ import {
   CUSTOM_PROVIDER_APIS,
   dispatchRefusals,
   doorRefusals,
+  gateLookWarnings,
+  gateScopeChecks,
+  standingPoolLines,
+  standingPoolRefusals,
   loadCharts,
   loadWorkflows,
   machineBodies,
+  mcpRefusals,
+  mcpUrlRefusals,
   openPartRefusals,
   partsOf,
   placementWalkOf,
@@ -106,7 +112,17 @@ export async function checkInstance(io: Io, root: string, config: JR2Config): Pr
   // and the door's walk cannot drift.
   // A zod `input` that no door reads (ADR-0033) is in the same listing, first: the door refuses it
   // with the same line.
-  const open = [...doorRefusals(workflows), ...openPartRefusals(workflows)];
+  // A standing Pool that is not the top Machine of its Workflow (ADR-0017) is in the listing too.
+  // An Agent's `mcp` list against the config's `mcp` block (ADR-0079) is in the same listing: a
+  // server name the block does not declare is refused as an Open part is, with its customize() line,
+  // and the door refuses the same lines. The urls are the host's alone (`.env`).
+  const open = [
+    ...doorRefusals(workflows),
+    ...standingPoolRefusals(workflows),
+    ...openPartRefusals(workflows),
+    ...mcpRefusals(workflows, config),
+    ...mcpUrlRefusals(config),
+  ];
   if (open.length) {
     for (const line of open) activity(io, `refusing: ${line}`);
     return undefined;
@@ -120,6 +136,15 @@ export async function checkInstance(io: Io, root: string, config: JR2Config): Pr
     for (const line of chartRefusals) activity(io, `refusing: ${line}`);
     return undefined;
   }
+  // Each `answer` item that names single Gates (ADR-0078) names Gates that the Workflow's Machines or
+  // its Chart files have: the door's own check, so a typo fails here and not at the first answer. A
+  // name that only a runtime Chart can have is a warning, because the host cannot see those Charts.
+  const gateScopes = gateScopeChecks(workflows, config, charts);
+  for (const line of gateScopes.warnings) activity(io, `warning: ${line}`);
+  if (gateScopes.errors.length) {
+    for (const line of gateScopes.errors) activity(io, `refusing: ${line}`);
+    return undefined;
+  }
   // What each same-Instance dispatch names resolves in this Assembly, and its slot schema matches
   // the callee's door (ADR-0071): the door's own check, so the publish would refuse the same lines.
   // The host cannot see the Orchestrator's volume, so a named Chart that is no Chart file here is a
@@ -130,6 +155,15 @@ export async function checkInstance(io: Io, root: string, config: JR2Config): Pr
     for (const line of dispatched.errors) activity(io, `refusing: ${line}`);
     return undefined;
   }
+  // A hooked Gate that a lost delivery can stop (ADR-0011, ADR-0054): no look and no `after` on its
+  // state, or a look that a package left Open and nobody bound. A warning, never a refusal: a person
+  // can still answer the Gate with `jr2 send`.
+  for (const line of gateLookWarnings(workflows)) activity(io, `warning: ${line}`);
+  // Each standing Pool (ADR-0017): the chain from each Hook that reaches it to its callee, and a
+  // warning when two of them dispatch to one Workflow, whose caps then add.
+  const standing = standingPoolLines(workflows, config.hooks);
+  for (const chain of standing.chains) activity(io, `standing: ${chain}`);
+  for (const line of standing.warnings) activity(io, `warning: ${line}`);
   // What each registered Machine runs outside itself (ADR-0067, ADR-0068): every Effect slot, with
   // the plain data it carries — a command's argv and its timeout; an http
   // Effect's method, its fixed target and the secrets it names — read, never run.
@@ -162,6 +196,18 @@ export async function checkInstance(io: Io, root: string, config: JR2Config): Pr
         );
         continue;
       }
+      if (e.kind === "mcp") {
+        // The server's url and secret are the config's (ADR-0079): the line names the server, and
+        // its timeout is the server's unless the Effect sets one.
+        const asks =
+          e.op === "call" ? `call ${e.server ?? "<open>"}/${e.tool ?? "<open>"}` : `${e.op} ${e.server ?? "<open>"}`;
+        const timeout = e.timeoutMs > 0 ? `${e.timeoutMs / 1000}s` : "the server's timeout";
+        activity(
+          io,
+          `  ${e.name}${where}: mcp ${asks} — ${timeout}, in the Instance Effector${e.idempotent ? ", idempotent" : ""}`,
+        );
+        continue;
+      }
       if (e.kind === "push") {
         const opts = (["pin", "sign", "squash", "force"] as const).filter((k) => e[k]);
         const slot = e.slot !== undefined ? `, in Repo Slot "${e.slot}"` : "";

package/src/instance.ts

@@ -11,10 +11,13 @@
 //     `config.name` > folder name): the Instance token is read from the in-cluster `jr2-instance`
 //     Secret and the `jr2-orchestrator` Service is port-forwarded for the life of the command —
 //     kube RBAC is the real gate, and no local state file can go stale (ADR-0019).
+//   - On the kube path the CLI says whom it acts for (ADR-0078): the user name a kube
+//     `SelfSubjectReview` gives for the context, sent as `jr2-on-behalf-of`. The Instance token is
+//     the Caller `token/instance`; the name says which person held it. With `--url` it says none.
 //   - Every resolution prints its target on stderr, so ambient-context drift stays visible.
 
 import { basename } from "node:path";
-import { loadConfig } from "@jr2/orchestrator/internal";
+import { loadConfig, ON_BEHALF_OF_MAX } from "@jr2/orchestrator/internal";
 import { INSTANCE_SECRET, kubectlKube, ORCHESTRATOR_PORT, ORCHESTRATOR_SERVICE } from "./kube.ts";
 import { assertKitVersion } from "./kit-version.ts";
 import { activity, type Io } from "./output.ts";
@@ -31,8 +34,9 @@ export function resolveRoot(cwd: string): string {
   return root;
 }
 
-/** Where to talk, as whom, and how to hang up (the port-forward lives only as long as the verb). */
-export type Target = { url: string; token?: string; close?: () => void };
+/** Where to talk, as whom, and how to hang up (the port-forward lives only as long as the verb).
+ * `onBehalfOf` is the party the CLI says it acts for (ADR-0078): on the kube path, the kube user. */
+export type Target = { url: string; token?: string; onBehalfOf?: string; close?: () => void };
 
 export type TargetOptions = {
   /** Explicit orchestrator address (`--url`); with `JR2_URL` the escape hatch past the kube path. */
@@ -90,6 +94,13 @@ export async function resolveTarget(io: Io, opts: TargetOptions): Promise<Target
       `not deployed here — right context? (context ${context}, namespace ${namespace}; \`jr2 up\` deploys)`,
     );
   }
-  const fwd = await kube.portForward({ namespace, service: ORCHESTRATOR_SERVICE, port: ORCHESTRATOR_PORT, ...ctx });
-  return { url: fwd.url, token, close: fwd.close };
+  // The kube user, read beside the forward so it costs no time of its own. A name past the
+  // header's bound is cut, never sent whole to a refusal. A name that is not printable ASCII is not
+  // sent: a header value cannot carry it, and the claim is not worth a failed verb.
+  const [fwd, user] = await Promise.all([
+    kube.portForward({ namespace, service: ORCHESTRATOR_SERVICE, port: ORCHESTRATOR_PORT, ...ctx }),
+    kube.selfSubject(ctx),
+  ]);
+  const onBehalfOf = user && /^[\x20-\x7e]+$/.test(user) ? user.slice(0, ON_BEHALF_OF_MAX).trim() : undefined;
+  return { url: fwd.url, token, ...(onBehalfOf ? { onBehalfOf } : {}), close: fwd.close };
 }

package/src/kube.ts

@@ -4,7 +4,7 @@
 // `KubePort` is what target resolution consumes (tests inject a fake), `kubectlKube` is the real
 // one, shelling out to the same `kubectl` a human debugging the cluster would use.
 
-import { execFile, spawn } from "node:child_process";
+import { execFile, spawn, type ChildProcess } from "node:child_process";
 import { setTimeout as sleep } from "node:timers/promises";
 import { promisify } from "node:util";
 
@@ -41,6 +41,11 @@ export type KubePort = {
    * cluster could not answer at all — the two are different faults (ADR-0019), and a caller that
    * merged them would send a user with a dead VPN off to check a context that is correct. */
   readSecret(opts: { namespace: string; name: string; key: string; context?: string }): Promise<string | undefined>;
+  /** The user name that the API server gives the current credentials, from a `SelfSubjectReview`
+   * (`kubectl auth whoami`): the party the CLI says it acts for (ADR-0078). Undefined when the
+   * server does not answer it. Never rejects: the name is a claim the CLI adds, and a verb does not
+   * fail for want of it. */
+  selfSubject(opts: { context?: string }): Promise<string | undefined>;
   /** Forward a Service port to an ephemeral local port for the life of the command. */
   portForward(opts: {
     namespace: string;
@@ -50,6 +55,21 @@ export type KubePort = {
   }): Promise<{ url: string; close: () => void }>;
 };
 
+/**
+ * A long-lived kubectl child (a port-forward) ends with this process. Node does not end a child
+ * when it exits, so a verb that `process.exit`s, or that a signal handler ends, leaves the child
+ * alive, and it holds an API-server stream. Here the child is killed on this process's `exit`.
+ * Returns the kill, which is also what `close` calls; the hook goes when the child closes.
+ */
+export function endsWithProcess(child: ChildProcess): () => void {
+  const kill = () => {
+    if (child.exitCode === null && child.signalCode === null) child.kill();
+  };
+  process.once("exit", kill);
+  child.once("close", () => process.removeListener("exit", kill));
+  return kill;
+}
+
 const ctxArgs = (context?: string): string[] => (context ? ["--context", context] : []);
 
 /** The loosely-typed kube object shape the converge logic inspects: labels carry the instance's
@@ -1139,6 +1159,19 @@ export const kubectlKube: KubePort = {
     }
   },
 
+  async selfSubject({ context }) {
+    try {
+      const { stdout } = await exec(
+        "kubectl",
+        [...ctxArgs(context), "auth", "whoami", "-o", "jsonpath={.status.userInfo.username}", ...reachArgs],
+        { timeout: REACH_BUDGET_MS },
+      );
+      return stdout.trim() || undefined;
+    } catch {
+      return undefined; // a server without the API, or RBAC that refuses it: no claim, and no failure
+    }
+  },
+
   // `:port` asks kubectl for an ephemeral local port, announced on its stdout as
   // "Forwarding from 127.0.0.1:<local> -> <remote>" — parsed rather than raced.
   portForward({ namespace, service, port, context }) {
@@ -1151,13 +1184,14 @@ export const kubectlKube: KubePort = {
         `service/${service}`,
         `:${port}`,
       ]);
+      const kill = endsWithProcess(child);
       let out = "";
       let err = "";
       // The forward is long-lived by design, so the bound is on its FIRST BYTE, not on the child:
       // silence here is the same unreachable cluster the Secret read just survived, and a verb that
       // waits forever for the announcement has only moved the hang one line down.
       const gaveUp = setTimeout(() => {
-        child.kill();
+        kill();
         reject(new Error(`kubectl port-forward: no answer after ${REACH_BUDGET_MS / 1000}s`));
       }, REACH_BUDGET_MS);
       gaveUp.unref?.();
@@ -1172,7 +1206,7 @@ export const kubectlKube: KubePort = {
       child.stdout.on("data", (d: Buffer) => {
         out += d.toString();
         const m = /Forwarding from 127\.0\.0\.1:(\d+)/.exec(out);
-        if (m) done({ url: `http://127.0.0.1:${m[1]}`, close: () => child.kill() });
+        if (m) done({ url: `http://127.0.0.1:${m[1]}`, close: kill });
       });
       child.stderr.on("data", (d: Buffer) => (err += d.toString()));
       child.on("error", (e) => failed(new Error(`kubectl port-forward failed: ${e.message}`)));