@jr2/orchestrator 0.1.0

package/src/agent.ts

@@ -0,0 +1,124 @@
+// The Agent definition (ADR-0018/0027): the part of an Agent a user genuinely owns — model +
+// instructions + workspace access — as SERIALIZABLE DATA. Everything mechanical (the Adapter
+// leash, the Working-tool assembly, the wire) lives in the stock Harness image (`@jr2/harness`),
+// which runs the definition it is handed and re-reads it per Submission.
+//
+// A definition is NOT an Instance roster entry: a Machine CARRIES it as an actor slot —
+// `jr2Setup({ actors: { coder: agent(def) } })`, invoked as `src: "coder"` (ADR-0049) — so the
+// Agent's name is the slot key and its scope is that one Machine. Two Machines in one run may
+// both carry a `coder`; neither can see the other's.
+//
+// This module is the plain-data contract plus the slot BRAND (`isAgent` — the readable
+// `definition` property `agent()` stamps on the logic). The brand lives HERE, apart from the
+// logic that carries it, so `jr2Setup`'s menu derivation can recognize an Agent slot without
+// pulling the wire client onto its load path.
+//
+// Since ADR-0054 the contract has two halves, and the split is the whole point: `AgentDefinition`
+// is the WIRE type — `model: string`, because a Symbol does not ride a Turn — while
+// `AgentDeclaration` is what an AUTHOR writes, whose `model` may be Open (open.ts) for a composer
+// to bind. `jr2 up` refuses an Open Agent before anything is built; the Agent actor refuses to
+// admit a Turn under one, as the second fence. Everything downstream of admission sees a
+// definition.
+
+import { open } from "./open.ts";
+
+/** jr2's reasoning-effort scale (ADR-0027) — a strict subset of the runtime's, so every value
+ * passes through unmapped; mirrored by `@jr2/harness`'s spec contract. */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+/** What an Agent may DO to the Workspace (ADR-0028) — and, through `"none"`, where its Turn runs
+ * (ADR-0031): the value the Agent actor reads off its own slot's definition to place the Turn. */
+export type WorkspaceAccess = "write" | "read" | "none";
+
+/** The plain-data Agent definition (ADR-0018). Must stay JSON-serializable: the definition rides
+ * the Turn to the Harness (ADR-0049), so anything non-serializable would be silently lost — grow
+ * this contract deliberately. ADR-0028 added a restriction vocabulary (`workspace`), not an
+ * extension one: custom tool implementations stay out of the contract. */
+export type AgentDefinition = {
+  /** Model specifier, `<provider>/<modelId>`, e.g. `anthropic/claude-sonnet-4-6`. REQUIRED —
+   * there is no instance-wide default (ADR-0018): `jr2.config.ts`'s `harness` section
+   * declares which providers are REACHABLE, and the definition makes the choice. This is also the
+   * only model `jr2 up` can preflight, since a workflow's is not statically recoverable. An
+   * invocation may override it for one Turn (`AgentTurnInput.model`). */
+  model: string;
+  /** The Agent's system prompt. */
+  instructions: string;
+  /** Optional static description — observability, never sent to the model. */
+  description?: string;
+  /** Working directory inside the Sandbox. Default `/work` — the pod volume the attach step put
+   * the worktrees on (ADR-0005); override only for non-Workspace layouts. */
+  cwd?: string;
+  /** Reasoning effort. Omitted → the runtime's default. An invocation may override it for one
+   * Turn (`AgentTurnInput.thinkingLevel`) — effort is a property of the task's difficulty, so the
+   * same persona legitimately runs at different settings in different Machines. */
+  thinkingLevel?: ThinkingLevel;
+  /** What this Agent may DO to the Workspace (ADR-0028) — the persona in one word, deliberately
+   * not `tools` (that names the control-plane Menu, what it may SAY). `"read"` withholds the
+   * write/edit Working tools; bash stays, so this states intent and stops the honest path — the
+   * detached review worktree is the containment. `"none"` withholds the ENTIRE Working toolset:
+   * the Menu-only Agent converses and picks from its Menu, nothing else (`cwd` is moot — only
+   * Working tools consume it) — and places the Turn on the Instance Harness (ADR-0031).
+   * Default `"write"`. */
+  workspace?: WorkspaceAccess;
+};
+
+/**
+ * The Agent as an author DECLARES it (ADR-0054): the definition, except that `model` may be Open —
+ * the one part a packaged Machine cannot honestly fill, since the package cannot pay for it. Every
+ * other field is the wire's, because every other field a package CAN state.
+ *
+ * This is what `agent()` takes and what the slot's brand carries, so the walk and `customize()`
+ * read the author's own answer, Open included. Nothing sends this: the wire takes an
+ * {@link AgentDefinition}, and {@link requireBoundAgent} is the one door between the two.
+ */
+export type AgentDeclaration = Omit<AgentDefinition, "model"> & { model: string | typeof open };
+
+/** The brand `agent(declaration)` stamps on its logic (ADR-0049): the declaration itself, readable
+ * off the logic object. Everything that must recognize an Agent slot reads THIS — never a name
+ * convention and never a roster. */
+export type AgentSlot = { definition: AgentDeclaration };
+
+/**
+ * Is this actor logic an Agent slot? What `jr2Setup` asks of every `actors` entry an invoke names,
+ * to decide whether the invoke gets a derived Menu, a minted instance id, and its slot key as the
+ * Agent name (ADR-0049) — replacing the retired `src === "agentRun"` test.
+ *
+ * Duck-typed on the brand, not an instanceof: a `.provide()`-substituted fake (the unit-test seam)
+ * is deliberately NOT an Agent slot — the wrapping already happened at createMachine time, against
+ * the declared slot.
+ *
+ * An Open model counts (ADR-0054): a Machine whose Agent nobody bound yet is still a Machine that
+ * carries an Agent, and the walk that refuses it has to SEE it first — an unrecognized slot would
+ * be reported as nothing at all.
+ */
+export function isAgent(logic: unknown): logic is AgentSlot {
+  if (typeof logic !== "object" || logic === null) return false;
+  const definition = (logic as { definition?: unknown }).definition;
+  if (typeof definition !== "object" || definition === null) return false;
+  const { model, instructions } = definition as Partial<AgentDeclaration>;
+  return (typeof model === "string" || model === open) && typeof instructions === "string";
+}
+
+/** Is this Agent's model still Open — nobody's answer yet (ADR-0054)? What the walk reports and
+ * the actor refuses on. */
+export function isOpenAgent(declaration: AgentDeclaration): boolean {
+  return declaration.model === open;
+}
+
+/**
+ * The declaration as the wire takes it, or a refusal naming the slot — the SECOND fence
+ * (ADR-0054). The first is `jr2 up`'s walk, which refuses an Open Agent on a registered Machine
+ * before anything is built; this one catches every path that walk never saw (a Machine invoked as
+ * itself in a test, an unregistered import composed mid-run) and it catches it before a Turn is
+ * admitted rather than as a Harness 400 with nothing but a slot key in it.
+ */
+export function requireBoundAgent(slot: string, declaration: AgentDeclaration): AgentDefinition {
+  if (typeof declaration.model !== "string") {
+    throw new Error(
+      `agent "${slot}" has an Open model — nobody bound it; bind it where the Machine is registered ` +
+        `(\`customize(<machine>, { agents: { ${slot}: { model: "<provider>/<model>" } } })\`), ` +
+        "because a packaged Machine cannot pick a model on your behalf (ADR-0054)",
+    );
+  }
+  return { ...declaration, model: declaration.model };
+}

package/src/ambient.ts

@@ -0,0 +1,50 @@
+// Ambient workspace coordinates (ADR-0016): how an Agent's turn finds its Harness without the
+// workflow threading `endpoint`/`sandbox` through every input. `workspace()`'s `running` state
+// co-invokes a REGISTRAR actor that records the wrapper's mechanism handles here, keyed by the
+// wrapper's own actorRef; the Agent actor walks `self._parent` to the nearest registered ancestor.
+//
+// Why an invoked actor and not an entry action: invoked actors restart on snapshot restore,
+// entry actions do not — so the registration is restore-safe by construction (the same property
+// the reconcile probe leans on, ADR-0012). Why the parent CHAIN: many concurrent workspaces
+// share one actor system, so a system-keyed map cannot carry per-workspace handles; the chain
+// resolves the ENCLOSING wrapper structurally, never a sibling's — which is what keeps
+// cross-feature event injection impossible and lets the registration record the right Sandbox
+// (ADR-0013's token scope) with zero consumer plumbing.
+//
+// A pure leaf (no flue, no machines) for the same reason as vocabulary.ts: actor.ts must reach
+// it without dragging workspace.ts (and its SandboxPort surface) onto the actor's load path.
+
+import type { AnyActorRef } from "xstate";
+
+/** The mechanism-facing handles a workspace registers: where the Harness is, WHICH Sandbox
+ * (ADR-0013 token scope), and the worktree geography the body-facing subset is cut from. */
+export type AmbientHandles = {
+  endpoint: string;
+  sandbox: string;
+  /** Every Repo Slot's branch-worktree path, by slot (ADR-0051). */
+  repos: Record<string, string>;
+  branch: string;
+  /** Detached review-worktree paths, when the spec carried `reviewSha` (ADR-0028). */
+  review?: Record<string, string>;
+};
+
+const byRef = new WeakMap<AnyActorRef, AmbientHandles>();
+
+/** Registrar-side: record a wrapper's handles under its actorRef; returns the disposer. */
+export function registerAmbientHandles(ref: AnyActorRef, handles: AmbientHandles): () => void {
+  byRef.set(ref, handles);
+  return () => {
+    // Dispose only our own entry (a re-registration on restore must not be clobbered late).
+    if (byRef.get(ref) === handles) byRef.delete(ref);
+  };
+}
+
+/** Actor-side: the nearest enclosing workspace's handles, via the actor parent chain.
+ * (`_parent` is typed public API on `ActorRef` — underscore-prefixed, not hidden.) */
+export function ambientHandlesFor(self: AnyActorRef): AmbientHandles | undefined {
+  for (let ref = self._parent; ref; ref = ref._parent) {
+    const handles = byRef.get(ref);
+    if (handles) return handles;
+  }
+  return undefined;
+}

package/src/config.ts

@@ -0,0 +1,297 @@
+// Instance configuration (ADR-0050): the deployment facts a Machine cannot carry — the instance's
+// identity and reach, what its Harness may reach, and how the cluster authenticates to Repos. What
+// a Sandbox is MADE of and which Repos it attaches are not here — they are `workspace()` options
+// (ADR-0037/0049/0051), and every image ref is resolved by `jr2 up` (ADR-0038). There is no `images`
+// block and nothing that names a Repo, deliberately: neither would type anything a Machine cannot
+// carry itself, and an override seat for the Harness ref is the eject hatch ADR-0027 refuses.
+//
+// `defineConfig` is an identity passthrough — it exists solely so a `jr2.config.ts` is checked
+// against `JR2Config` at authoring time and in `jr2 up`'s typecheck gate (ADR-0050), exactly like
+// the config helpers in vite/tsup/etc. No runtime behavior beyond returning its argument. It is
+// NOT generic: the parameter is `JR2Config` itself, so the literal an author writes gets
+// excess-property checking at every depth. A generic `<T extends JR2Config>` would infer `T` as
+// the literal's own type and check nothing an extra key could break — a `tokn` on a
+// `git.credentials` entry would compile, and that entry would admit its prefix through the fence
+// anonymously (ADR-0051). Nothing reads the literal's type back, so the generic buys nothing.
+
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { z } from "zod";
+import { repoIdentity } from "./repo-identity.ts";
+
+// ------------------------------------------------------------------------------------------------
+// `git.credentials` (ADR-0051): how the cluster authenticates to a Repo, and the fence.
+//
+// A Repo is identified by its url and nothing in this file names one (CONTEXT.md "Repo"). What
+// the config declares is CREDENTIALS, matched by prefix on the identity — the Argo and Flux shape.
+// The Orchestrator resolves the entry when it creates a Repo CR and writes a `secretRef`; the
+// cache agent reads only that. The list is also the fence: a per-run url (run input, a ticket
+// field) that matches no entry is refused at attach, so nothing can spend this cluster's
+// credential against an arbitrary host. A bound url is code the Instance typechecked and deployed
+// — admitted without a match, cloned anonymously.
+
+/** One credentials entry. An entry may carry neither `token` nor `sshKey`: it then admits its
+ * prefix through the fence and the clone is anonymous. */
+export type GitCredential = {
+  /** A prefix on the identity (`github.com/ourorg/`), or `*` for everything. */
+  match: string;
+  /** Env var name holding an HTTPS token; `jr2 up` materializes its value into the Instance Secret. */
+  token?: string;
+  /** A Secret (Flux key names: `identity`, `identity.pub`, `known_hosts`) holding a deploy key. */
+  sshKey?: string;
+};
+
+export type GitConfig = {
+  /** Matched by prefix on the Repo identity; the longest `match` wins, ties → first in the list. */
+  credentials?: readonly GitCredential[];
+};
+
+/** The entry for an identity: `*` matches everything at length 0, else a prefix match; the
+ * longest `match` wins, and a tie goes to the first in the list. `undefined` when none matches —
+ * which the fence reads as "refuse a per-run url". */
+export function matchCredential(identity: string, list: readonly GitCredential[]): GitCredential | undefined {
+  let best: { entry: GitCredential; length: number } | undefined;
+  for (const entry of list) {
+    const length = entry.match === "*" ? 0 : identity.startsWith(entry.match) ? entry.match.length : -1;
+    if (length < 0) continue;
+    if (best === undefined || length > best.length) best = { entry, length };
+  }
+  return best?.entry;
+}
+
+/** The Secret a Repo CR's `secretRef` names for `url` under `entry`, picked by the url's scheme:
+ * https/http spend a token (a Secret the Orchestrator derives from the env var), ssh spends the
+ * named deploy-key Secret. `undefined` when no entry, no applicable field, or a scheme that carries
+ * no credential (`git://`, a local path) — the clone is anonymous. */
+export function credentialSecretFor(
+  url: string,
+  entry: GitCredential | undefined,
+): { kind: "token"; env: string; secret: string } | { kind: "ssh"; secret: string } | undefined {
+  if (entry === undefined) return undefined;
+  const { scheme } = repoIdentity(url);
+  if ((scheme === "https" || scheme === "http") && entry.token !== undefined)
+    return { kind: "token", env: entry.token, secret: gitTokenSecretName(entry.match) };
+  if (scheme === "ssh" && entry.sshKey !== undefined) return { kind: "ssh", secret: entry.sshKey };
+  return undefined;
+}
+
+/** The token Secret's name for one entry — deterministic in `match`, so a redeploy finds its own
+ * Secret and two entries never share one. */
+export function gitTokenSecretName(match: string): string {
+  return `jr2-git-${createHash("sha256").update(match).digest("hex").slice(0, 8)}`;
+}
+
+/** Whether `url` clones over ssh — scp-style `git@host:path`, `ssh://`, or `git+ssh://`. A url
+ * that does not parse is not an ssh url. */
+export function isSshUrl(url: string): boolean {
+  try {
+    return repoIdentity(url).scheme === "ssh";
+  } catch {
+    return false;
+  }
+}
+
+/** An env var on the Harness container, in the CR's (corev1.EnvVar) shape — `value` or a
+ * `valueFrom` secret/configmap reference, passed through to the operator verbatim. */
+export type HarnessEnvVar = {
+  name: string;
+  value?: string;
+  valueFrom?: Record<string, unknown>;
+};
+
+/** A whole-Secret/ConfigMap env injection (corev1.EnvFromSource) for the Harness container —
+ * e.g. `{ secretRef: { name: "anthropic" } }` to hand a real Harness its model API key. */
+export type HarnessEnvFromSource = {
+  secretRef?: { name: string };
+  configMapRef?: { name: string };
+};
+
+/** This kit's version — npm version == published image tag, one release train (ADR-0019). */
+export const KIT_VERSION = (
+  JSON.parse(await readFile(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")) as {
+    version: string;
+  }
+).version;
+
+/** Token limits for one model — the Harness's provider-registration options, keyed per model because limits are
+ * properties of the MODEL, not the endpoint (agents pick models per definition, ADR-0018). */
+export type HarnessProviderModel = {
+  /** The model's context window, in tokens (vLLM: `max_model_len`). */
+  contextWindow?: number;
+  /** The model's max output tokens per completion. */
+  maxTokens?: number;
+};
+
+/** A custom model provider (ADR-0018) — what the stock Harness registers with pi's
+ * `registerProvider(id, { api, baseUrl, … })` (ADR-0027). The vLLM/Ollama path: an OpenAI-compatible
+ * endpoint under an instance-chosen provider id. */
+export type HarnessProvider = {
+  /** The provider id model specifiers use (`<id>/<model>`), e.g. `vllm`. */
+  id: string;
+  /** The wire protocol, e.g. `openai-completions` (most OpenAI-compatible endpoints). */
+  api: string;
+  /** The endpoint — reachable FROM PODS (`localhost` never is; a LAN address works on kind).
+   * Deployment-varying → resolve from env (`.env`), never hardcode (ADR-0019). */
+  baseUrl: string;
+  /** API key, when the endpoint wants one. May read `process.env` — `jr2 up` materializes config
+   * env values into the instance's Secret; the literal never lands in a manifest (ADR-0019).
+   * Genuinely optional: an unauthenticated endpoint needs none (the Harness sends the wire
+   * library's placeholder, which vLLM/Ollama ignore). */
+  apiKey?: string;
+  /** Endpoint-wide default token limits, for any model this provider serves. Flue resolves
+   * per-model → provider-level → catalog → 0, and a CUSTOM provider id has no catalog entry —
+   * unset limits resolve to 0, which leaves auto-compaction no context budget to reason about
+   * (the wire request itself is fine: a 0 `maxTokens` is omitted, never sent). */
+  contextWindow?: number;
+  maxTokens?: number;
+  /** Per-model limits, keyed by the model id AFTER the provider prefix — the map entry for
+   * `vllm/Qwen/Qwen3-32B` is `"Qwen/Qwen3-32B"`. Committable model properties, not
+   * deployment-varying: whichever model an Agent definition names resolves its own entry. */
+  models?: Record<string, HarnessProviderModel>;
+};
+
+/** The agent-runtime section (ADR-0018): what the stock Harness image consumes alongside the
+ * Agent definition each Turn hands it (ADR-0049). Moved out of `sandbox` deliberately — `sandbox`
+ * is pod transport (it still CARRIES this env to the Harness container), but model concerns are
+ * Harness semantics.
+ *
+ * It declares what this instance can REACH — endpoints, credentials, trust — and never WHICH
+ * model to use (ADR-0018). This config holds no instance-wide `model` default and no Agent
+ * roster: an Agent is an actor slot on ONE Machine, whose definition rides the Turn (ADR-0049).
+ * One definition value may still be carried by several Machines, so the variation that matters is
+ * per-definition and per-invocation, which one global default serves not at all. */
+export type HarnessConfig = {
+  /** Custom model provider, preflighted from inside the cluster by `jr2 up` (ADR-0019). */
+  provider?: HarnessProvider;
+  /** Env vars for the Harness container (Agent creds, e.g. ANTHROPIC_API_KEY). Values read from
+   * `process.env`/`.env` are materialized into the instance-owned Secret by `jr2 up`. */
+  env?: readonly HarnessEnvVar[];
+  /** Whole-Secret/ConfigMap env for the Harness container — `envFrom` refs to Secrets YOU manage
+   * (Sealed Secrets etc.); `jr2 up` preflights that each referenced Secret exists (ADR-0019). */
+  envFrom?: readonly HarnessEnvFromSource[];
+  /** Path to a PEM CA bundle, RELATIVE to the instance folder — commit the file (CA certs are
+   * public; e.g. an internal CA in front of a LAN vLLM). Only `jr2 up` reads it (host-side): it
+   * materializes the `jr2-ca` ConfigMap and runs the provider preflight with the same trust. The
+   * bundle lands on the Harness container and NOWHERE else — never the Adapter, whose Orchestrator
+   * credential has no business behind the same trust store (the `harness.env` asymmetry,
+   * ADR-0013/0020). */
+  caBundle?: string;
+};
+
+/** One pod-spec toleration, verbatim (ADR-0052): `nodeSelector` and `tolerations` are the raw
+ * Kubernetes shapes, the stance `HarnessEnvVar` takes for `EnvVar`. */
+export type Toleration = {
+  key?: string;
+  operator?: "Exists" | "Equal";
+  value?: string;
+  effect?: "NoSchedule" | "PreferNoSchedule" | "NoExecute";
+  tolerationSeconds?: number;
+};
+
+/**
+ * Where an Instance's Sandboxes may land (ADR-0052). Absent, a Sandbox node is wherever an
+ * ordinary pod lands — not cordoned, no taint — and no jr2 label is ever required. Both keys ride
+ * the Sandbox pod verbatim, the Repo cache agent's DaemonSet takes the same two so a cache is only
+ * ever where a Sandbox can reach it, and `jr2 up` reads the same predicate off the nodes to report
+ * the set. A Machine says nothing about placement: a node label is a deployment fact (ADR-0050).
+ * These two are the default class; a per-Machine `classes` map is the deferred extension.
+ */
+export type SandboxPlacement = {
+  /** Pod `spec.nodeSelector`: a node must carry every label. */
+  nodeSelector?: Readonly<Record<string, string>>;
+  /** Pod `spec.tolerations`, verbatim — no `tolerationSeconds` is added, so a tolerated `NoExecute`
+   * taint keeps a Sandbox through it for as long as its Lease is renewed. */
+  tolerations?: readonly Toleration[];
+};
+
+export type JR2Config = {
+  /** The instance's identity (ADR-0019): its kube namespace defaults to this (`-n` overrides),
+   * and `jr2 up` labels every object it owns with it. Default: the instance folder's name. */
+  name?: string;
+  /** How the cluster authenticates to Repos, and the fence a per-run url must pass (ADR-0051).
+   * NOT a list of Repos: a Machine names those itself, through its `workspace()`'s Repo Slots, and
+   * whether the instance has a data plane at all is read off the registered Machines. */
+  git?: GitConfig;
+  /** Agent-runtime config for the stock Harness (see `HarnessConfig`). */
+  harness?: HarnessConfig;
+  /** Which nodes are this Instance's Sandbox nodes (see `SandboxPlacement`, ADR-0052). Absent →
+   * wherever an ordinary pod lands. */
+  sandbox?: SandboxPlacement;
+  /** Image registry prefix (deployment-varying — resolve from env). Absent → images are
+   * `kind load`-ed; present → pushed. A non-kind cluster without one fails loudly (ADR-0019). */
+  registry?: string;
+  /** Where this cluster pulls the PUBLISHED Kit images from (deployment-varying — resolve from
+   * env). Absent → the canonical home, `ghcr.io/snapwich/jr2-harness:<kitversion>` and friends;
+   * present → the same tags re-homed to a self-hosted mirror, `<kitRegistry>/jr2-harness:<ver>`,
+   * for a self-hosted, air-gapped, or mirror-only cluster (ADR-0044). Seeding that mirror is a
+   * deliberate, instance-less act (`jr2 kit push`), never a side effect of `jr2 up`.
+   *
+   * Separate from `registry` on purpose: `registry` addresses images THIS converge builds,
+   * `kitRegistry` addresses artifacts the kit already published. One key for both would make every
+   * private-registry user mirror three images they could have pulled from the home. */
+  kitRegistry?: string;
+  /** What `jr2 up` builds its images FOR — docker platform strings, e.g. `["linux/arm64"]`
+   * (deployment-varying — resolve from env). Absent → derived from the cluster's schedulable nodes
+   * and intersected with the platforms the kit releases for, which is the answer for every ordinary
+   * cluster (ADR-0045). Present → ABSOLUTE: derivation is skipped and this is the build set (still
+   * intersected, so an unpublished platform is a named error, never a silent build).
+   *
+   * The escape hatch for the two cases derivation cannot see: a pool that autoscales from zero (no
+   * nodes to read yet), and a polluted set (an amd64 GPU pool beside arm64 workers, where the
+   * derived pair would cost a needless qemu cross-build). Not additive or subtractive. */
+  platforms?: readonly string[];
+  /** Operator-layer overrides — kit development territory (ADR-0019). */
+  operator?: {
+    /** `false` = `jr2 up` skips the operator layer (run the controller loop yourself). */
+    manage?: boolean;
+  };
+};
+
+/** Identity passthrough that checks a config object against `JR2Config` where it is written —
+ * excess keys included, at every depth, which is why the parameter is the type and not a generic
+ * bound by it. */
+export function defineConfig(c: JR2Config): JR2Config {
+  return c;
+}
+
+/**
+ * Load an instance's `jr2.config.ts` (default export). Absent file → undefined (an instance
+ * can boot configless); a file that fails to IMPORT throws — a broken config must be loud,
+ * never silently treated as "no config". The one shape check lives here, on the path the host
+ * CLI and the in-cluster Orchestrator share: `git.credentials` is checked at runtime, because an
+ * instance is zero-build and nothing typechecks this file before Node strips its types and
+ * imports it.
+ */
+export async function loadConfig(dir: string): Promise<JR2Config | undefined> {
+  const file = join(dir, "jr2.config.ts");
+  if (!existsSync(file)) return undefined;
+  const mod = (await import(pathToFileURL(file).href)) as { default?: JR2Config };
+  if (!mod.default) throw new Error(`${file} has no default export (use \`export default defineConfig({…})\`)`);
+  if (mod.default.git !== undefined) checkGit(mod.default.git, file);
+  return mod.default;
+}
+
+const NonEmpty = z.string().min(1);
+const Credential = z.object({ match: NonEmpty, token: NonEmpty.optional(), sshKey: NonEmpty.optional() }).strict();
+
+/** `git.credentials`' SHAPE, checked at load — by index and field, so a bad entry names itself
+ * (`git.credentials[1].token`) rather than surfacing as a Secret that never matches. */
+function checkGit(git: unknown, where: string): void {
+  if (typeof git !== "object" || git === null || Array.isArray(git))
+    throw new Error(`${where} at git: expected an object — ${GIT_HINT}`);
+  const { credentials } = git as { credentials?: unknown };
+  if (credentials === undefined) return;
+  if (!Array.isArray(credentials)) throw new Error(`${where} at git.credentials: expected an array — ${GIT_HINT}`);
+  for (const [i, entry] of credentials.entries()) {
+    const parsed = Credential.safeParse(entry);
+    if (parsed.success) continue;
+    const issue = parsed.error.issues[0];
+    const at = ["", ...(issue?.path ?? [])].map(String).join(".");
+    throw new Error(`${where} at git.credentials[${i}]${at}: ${issue?.message ?? "invalid"} — ${GIT_HINT}`);
+  }
+}
+
+const GIT_HINT = "an entry is { match, token?, sshKey? } (ADR-0051)";