@jr2/orchestrator 0.1.0

package/src/images.ts

@@ -0,0 +1,303 @@
+// The resolved key→ref image map, from the READ side (ADR-0037/0038/0049). `jr2 up` builds every
+// image it deploys and writes this map into the `jr2-images` ConfigMap; the Sandbox port consults it
+// when it creates a pod. This module is the shape both sides agree on — deliberately its own file,
+// not folded into sandbox-kubectl.ts, because the CLI needs the type without dragging in the
+// kubectl port.
+//
+// The map is NESTED, never flat. The kit's own `harness`/`adapter` refs sit beside a `sandbox`
+// sub-map, so a user image can never shadow them — and `default` is the one reserved key in that
+// sub-map, because ADR-0037's fallback chain is built on it.
+//
+// A user image's key is its build context's CONTENT DIGEST (ADR-0049). That is what lets the two
+// sides agree without a path table: a Machine names its context as a `file:` URL, whose absolute
+// path differs between the host at `jr2 up` and the baked Orchestrator, while the FOLDER is the same
+// folder — the instance's `node_modules` holds the very tree the converge hashed. Digest in, digest
+// out, no dirname registry in between.
+//
+// There is NO cache and NO memo for the map itself. The whole reason it arrives as a mounted
+// ConfigMap rather than Deployment env (ADR-0038) is that a Dockerfile edit must not roll the
+// Orchestrator and put every live run through snapshot restore; a read-once cache would give back
+// exactly the stale-ref behavior the mount exists to avoid. The cost is a plain file read per
+// provision.
+
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Every image ref one converge resolved. `harness`/`adapter` are the kit's own (built from a kit
+ * checkout, or the published `<kitversion>` tags); `sandbox` is the instance's own docker-context
+ * builds — one `docker build` straight to a content tag, carrying no jr2 layers at all, because the
+ * Harness arrives at POD time on the `/opt/jr2` volume (ADR-0037).
+ *
+ * A registry REF is deliberately absent from this map and always will be: it is never built,
+ * never labeled, never swept, and never inspected at converge (ADR-0037/0039 — what jr2 did not
+ * stamp, jr2 does not touch). It needs no entry because it already IS its own ref.
+ */
+export type ImageRefs = {
+  /** The stock Harness image — also the last leg of the Sandbox Image fallback chain. */
+  harness: string;
+  /** The Adapter image (ADR-0013). An Agent with no Adapter cannot drive its Machine at all, so
+   * this is required: a map without it fails the provision rather than shipping a mute pod. */
+  adapter: string;
+  /** Built Sandbox Images by their build context's CONTENT DIGEST (ADR-0049), plus the reserved
+   * key `default` — the Instance's `images/default`, ADR-0037's middle leg. Empty when the
+   * instance ships no context and scaffolded no default. */
+  sandbox: Record<string, string>;
+  /**
+   * What each BUILT Sandbox Image's `USER` is, keyed by the same key — the answer to a
+   * question a provision cannot ask. ADR-0037 gives an image that declares no user a fallback
+   * (uid 1000, `HOME=/home/jr2` on an emptyDir), and only the host that built the image can see
+   * which case it is: `docker inspect` at converge is free, the cluster has no such reach.
+   *
+   * `""` is DATA, not a missing value: it is docker's own answer for "declares none", and it is
+   * exactly what the fallback turns on. An ABSENT key means jr2 did not build the image — a
+   * registry ref by construction, never built, never inspected — so it runs as whatever its own
+   * `USER` says, and one that would run as root fails the Harness container's `runAsNonRoot`.
+   * Optional so an older converge's map still reads: absent reads as "nothing known", which
+   * applies no fallback, which is the safe direction (the image keeps its own identity).
+   */
+  sandboxUser?: Record<string, string>;
+};
+
+/**
+ * Read the map the CLI wrote, per call. Absent or unparseable is a POINTED error naming the path
+ * and `jr2 up` — never a fallback onto a published tag: in a kit checkout the Harness is built to a
+ * content-addressed tag, so a literal `jr2-harness:<kitversion>` fallback would name a tag that was
+ * never built, and more importantly it would be the eject hatch ADR-0027/0038 refuse (nobody gets
+ * to run a hand-picked Harness against a real cluster).
+ */
+export async function readImageRefs(path: string): Promise<ImageRefs> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (err) {
+    throw new Error(
+      `no image map at ${path} (${(err as NodeJS.ErrnoException).code ?? "read failed"}) — every Sandbox ` +
+        "image is resolved from the `jr2-images` ConfigMap, which `jr2 up` writes when it builds the " +
+        "instance's images (ADR-0038). Converge this instance with `jr2 up`.",
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `the image map at ${path} is not JSON (${err instanceof Error ? err.message : err}) — it is written by ` +
+        "`jr2 up`; re-run it to rewrite the `jr2-images` ConfigMap (ADR-0038).",
+    );
+  }
+  const bad = (why: string): never => {
+    throw new Error(`the image map at ${path} is malformed: ${why} — re-run \`jr2 up\` (ADR-0038).`);
+  };
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) bad("expected a JSON object");
+  const map = parsed as Record<string, unknown>;
+  const ref = (key: string): string => {
+    const value = map[key];
+    if (typeof value !== "string" || !value) bad(`no \`${key}\` ref (got ${JSON.stringify(value)})`);
+    return value as string;
+  };
+  const harness = ref("harness");
+  // Required, not optional: with the ref living in the map there is no "no adapter configured"
+  // branch left to gate on, and an Agent whose pod has no Adapter parks forever on a tool call it
+  // cannot make (ADR-0013). Failing the provision is the only honest outcome.
+  const adapter = ref("adapter");
+  const sandboxRaw = map["sandbox"];
+  if (sandboxRaw !== undefined && (typeof sandboxRaw !== "object" || sandboxRaw === null || Array.isArray(sandboxRaw)))
+    bad("`sandbox` must be an object of name → ref");
+  const sandbox: Record<string, string> = {};
+  for (const [name, value] of Object.entries((sandboxRaw ?? {}) as Record<string, unknown>)) {
+    if (typeof value !== "string" || !value) bad(`\`sandbox.${name}\` is not a ref (got ${JSON.stringify(value)})`);
+    sandbox[name] = value as string;
+  }
+  const userRaw = map["sandboxUser"];
+  if (userRaw !== undefined && (typeof userRaw !== "object" || userRaw === null || Array.isArray(userRaw)))
+    bad("`sandboxUser` must be an object of name → USER");
+  const sandboxUser: Record<string, string> = {};
+  for (const [name, value] of Object.entries((userRaw ?? {}) as Record<string, unknown>)) {
+    // `""` is admitted deliberately — it is docker's answer for "declares no USER", the fact the
+    // fallback turns on. Only a non-string is malformed.
+    if (typeof value !== "string") bad(`\`sandboxUser.${name}\` is not a USER (got ${JSON.stringify(value)})`);
+    sandboxUser[name] = value as string;
+  }
+  return { harness, adapter, sandbox, sandboxUser };
+}
+
+/**
+ * Which of ADR-0037's two origins an image string names, told apart by SHAPE alone: a `file:` URL
+ * is a docker CONTEXT the Machine's module ships (`import.meta.resolve("./image")` — the only way
+ * an ES module can name a folder it owns), and anything else is a registry REF.
+ *
+ * Shape is the whole test on purpose: it needs no lookup, so it gives the same answer on the CLI's
+ * side and here. There is no third shape any more — the `images/<name>` dirname retired with
+ * dirname discovery (ADR-0049/0050), so a bare `ubuntu` is now what it looks like, a ref.
+ */
+export function isImageContext(image: string): boolean {
+  return image.startsWith("file:");
+}
+
+/**
+ * The content address of a build context: everything in that directory, with NO exclusions — and
+ * nothing else (ADR-0037/0038).
+ *
+ * It lives HERE, not in the CLI's build module, because BOTH sides compute it: `jr2 up` keys the
+ * map it publishes by this digest, and the baked Orchestrator computes it again at provision to
+ * look the ref up. One implementation is what makes "the host and the pod agree without a path
+ * table" true rather than hopeful (ADR-0049).
+ *
+ * No exclusions is deliberate: that directory IS the build context and it carries no
+ * `.dockerignore`, so a `dist/` or `node_modules/` beside the Dockerfile is image content and must
+ * be image address. The resolved harness ref is likewise NOT an input — the Harness arrives on a
+ * pod volume, so a kit edit moves the harness image's own tag and re-images future pods while
+ * every Sandbox Image tag stands still.
+ */
+export async function imageContextDigest(dir: string): Promise<string> {
+  const h = createHash("sha256");
+  // A domain separator, and the whole of it: a Sandbox Image's build is `docker build` of the
+  // user's own directory with no generated text anywhere in it, so — unlike the instance image,
+  // whose generated Dockerfile is image content the context never holds — there is nothing to salt
+  // WITH. The constant only keeps this hash's domain apart from the bundle's.
+  h.update("salt:sandbox\n");
+  const walk = async (root: string, d: string): Promise<void> => {
+    const entries = (await readdir(d, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) await walk(root, p);
+      // Symlinks are skipped, as they are for every other content address jr2 takes: a link's
+      // content is its target's path, which is host geography, not image content.
+      else if (e.isFile()) {
+        h.update(`0:${relative(root, p)}\n`);
+        h.update(await readFile(p));
+      }
+    }
+  };
+  await walk(dir, dir);
+  return h.digest("hex").slice(0, 12);
+}
+
+/**
+ * The map key one image string resolves to: a CONTEXT is keyed by its content digest, a REF is its
+ * own key and is never looked up. Absent is the reserved `default` key — ADR-0037's middle leg.
+ *
+ * A context whose folder is unreadable fails HERE, before a Secret or a CR exists, naming the path:
+ * in a deployed Orchestrator that means the module shipped a context the instance bundle does not
+ * hold, which is a packaging bug and not a cluster one.
+ */
+async function imageKey(image: string): Promise<string> {
+  if (!isImageContext(image)) return image;
+  const dir = fileURLToPath(image);
+  try {
+    return await imageContextDigest(dir);
+  } catch (err) {
+    throw new Error(
+      `the Sandbox Image context ${image} cannot be read (${(err as NodeJS.ErrnoException).code ?? "read failed"}) — ` +
+        "a `file:` image names a docker context the Machine's own module ships (ADR-0037), so it must travel " +
+        `with the module: check that ${dir} exists in the instance's node_modules.`,
+    );
+  }
+}
+
+/**
+ * One resolved Sandbox Image (ADR-0037): the ref the pod runs, plus the two seat facts only the
+ * host that BUILT it could see. One call rather than three, because all three answers must come
+ * off the same leg of the resolution chain — split, they could disagree.
+ */
+export type ResolvedImage = {
+  /** The ref the primary container runs. */
+  ref: string;
+  /**
+   * The image declares no `USER`, so ADR-0037's fallback seat applies: uid 1000 with
+   * `HOME=/home/jr2` on an emptyDir.
+   *
+   * Only a recorded `""` — docker's own answer for "declares none" — sets this. Everything else is
+   * false, and each for its own reason: a registry ref was never inspected (its own `USER` stands,
+   * and a root one fails `runAsNonRoot` at provision, named from the pod's own status rather than
+   * silently patched); the stock Harness declares `USER 1000` itself; and an unrecorded key is a
+   * map an older converge wrote, where "nothing known" must leave the image's identity alone.
+   */
+  fallbackSeat: boolean;
+  /**
+   * The recorded `USER` the kubelet will REFUSE, when it will.
+   *
+   * Every jr2-owned seat carries `runAsNonRoot: true` and names no `runAsUser` (the image's own
+   * `USER` decides — ADR-0005), and the kubelet resolves that pairing before it ever starts the
+   * container. Two recorded values lose there: a non-numeric name (`USER dev`), which the kubelet
+   * cannot prove is non-root because it does not read the image's `/etc/passwd`, and uid 0
+   * (`USER root`, `USER 0`), which plainly is root.
+   *
+   * Both surface as CreateContainerConfigError on the FIRST init step that runs the image — the
+   * preflight — and that container never starts, so `kubectl logs -c preflight` prints nothing. The
+   * record is the one place that can see it coming: `docker inspect` at converge already put the
+   * string in the map, so the provision can fail BEFORE it applies anything. Only a BUILT image is
+   * knowable here; a registry ref was never inspected, so it answers undefined and that pod is
+   * caught later, from the cluster (`rootImageFault` in sandbox-kubectl.ts) — same fault, same fix,
+   * one round trip more expensive.
+   */
+  refusedUser?: string;
+};
+
+/** The recorded `USER`, judged. `uid:gid` is split because docker records the whole `USER` line;
+ * only the uid half decides. */
+function judgeUser(recorded: string | undefined): Pick<ResolvedImage, "fallbackSeat" | "refusedUser"> {
+  // `""` is the fallback's trigger, not a failure (ADR-0037 supplies uid 1000); absent is unknown.
+  if (recorded === undefined) return { fallbackSeat: false };
+  if (recorded === "") return { fallbackSeat: true };
+  const uid = recorded.split(":")[0]!;
+  if (!/^\d+$/.test(uid) || Number(uid) === 0) return { fallbackSeat: false, refusedUser: recorded };
+  return { fallbackSeat: false };
+}
+
+/**
+ * Look one built key up in the map this converge wrote — for the Sandbox Image and the User
+ * Container alike, because ADR-0005 gives the User Container "the same resolution" deliberately.
+ *
+ * An unknown key throws: a converge-time check is impossible for a ref and unnecessary for a
+ * context (the walk built every one it found), so this fires when the Orchestrator's own
+ * `node_modules` holds a context the LAST converge did not build — a stale deployment. The error
+ * says exactly that, because "re-run `jr2 up`" is the whole fix.
+ */
+function builtRef(refs: ImageRefs, key: string, image: string, what: string): string {
+  const ref = refs.sandbox[key];
+  if (ref === undefined) {
+    throw new Error(
+      `no ${what} for ${image} (context digest ${key}) — this instance's last converge built ` +
+        `${Object.keys(refs.sandbox).length} image(s), none of them this one. Re-run \`jr2 up\`: it walks the ` +
+        "registered Machines and builds every `file:` context they carry (ADR-0037/0049).",
+    );
+  }
+  return ref;
+}
+
+/**
+ * ADR-0037's resolution chain: the wrapper's `image` (a context or a ref) → the Instance's
+ * `images/default` → the stock Harness. The last leg comes out of the MAP rather than a
+ * `jr2-harness:${KIT_VERSION}` literal, because in a kit checkout the Harness is built to a
+ * content-addressed tag (ADR-0038) and a literal would name a tag nothing ever built.
+ *
+ * A REF passes through VERBATIM. It is deployed-never-built: jr2 never built it, so jr2 has no ref to
+ * look up and nothing to say about its tag discipline — the cluster pulls it, and nothing was
+ * inspected, so no seat fact is known.
+ */
+export async function resolveSandboxImage(refs: ImageRefs, image?: string): Promise<ResolvedImage> {
+  if (image === undefined) {
+    const ref = refs.sandbox["default"];
+    if (ref === undefined) return { ref: refs.harness, fallbackSeat: false };
+    return { ref, ...judgeUser(refs.sandboxUser?.["default"]) };
+  }
+  if (!isImageContext(image)) return { ref: image, fallbackSeat: false };
+  const key = await imageKey(image);
+  return { ref: builtRef(refs, key, image, "Sandbox Image"), ...judgeUser(refs.sandboxUser?.[key]) };
+}
+
+/**
+ * The User Container's image (ADR-0005). Same two origins, same resolution — and NO fallback
+ * chain: absence means the pod has no third container, so there is nothing for a default to be.
+ * The seat's identity is "what jr2 does not own", and a jr2-chosen default would be an opinion in
+ * the one place ADR-0005 promises none. Its `USER` is not judged either: the seat carries no
+ * `securityContext` at all, so root is allowed there.
+ */
+export async function resolveUserImage(refs: ImageRefs, image: string): Promise<string> {
+  if (!isImageContext(image)) return image;
+  return builtRef(refs, await imageKey(image), image, "User Container image");
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// @jr2/orchestrator — the deployed app that runs Machines: workflow config, the agent + gate
+// delivery surfaces, the duplex Actor over the Harness wire, and durable snapshot persistence
+// (ADR-0002/0006/0007). Builds on the `@jr2/agent-protocol` wire contract.
+//
+// It does NOT speak MCP (ADR-0013): the Agent's MCP surface is hosted by the Adapter, in the
+// Sandbox. What lives here is the registration table and two thin HTTP adapters over it.
+
+// The wire contract, re-exported: a workflow authors against ONE package (`defineEvent`,
+// `jr2Setup`, `workspace`, … all import from "@jr2/orchestrator" — ADR-0015).
+export * from "@jr2/agent-protocol";
+export * from "./agent.ts";
+export * from "./parts.ts";
+export * from "./customize.ts";
+export * from "./ambient.ts";
+export * from "./config.ts";
+export * from "./repo-identity.ts";
+export * from "./pool.ts";
+export * from "./setup.ts";
+export * from "./vocabulary.ts";
+export * from "./tokens.ts";
+export * from "./durability.ts";
+export * from "./snapshot-store.ts";
+export * from "./actor.ts";
+export * from "./gate.ts";
+export * from "./workspace.ts";
+export * from "./images.ts";
+export * from "./sandbox-kubectl.ts";
+export * from "./repos.ts";
+export * from "./repo-fetch.ts";
+// Type-only: what a workflow event delivery looks like (the registration TABLE stays internal —
+// ADR-0011: workflows speak only defineEvent/agent/gate).
+export type { DeliveredEvent } from "./registration.ts";
+export * from "./machine-doc.ts";
+export * from "./run-host.ts";
+export * from "./http.ts";
+export * from "./harness-client.ts";
+export * from "./stub-harness.ts";
+export * from "./instance.ts";
+export * from "./server.ts";
+export * from "./names.ts";

package/src/instance.ts

@@ -0,0 +1,294 @@
+// The instance bootstrap (ADR-0008/0009): turn an instance folder into a *running* orchestrator.
+// This is the core of the deployed app's entrypoint (`serverMain`) — the seam that assembles the
+// slice-1/2/3 pieces into one process:
+//
+//   1. open the durable snapshot store (sqlite at `<dir>/.jr2/state.db` by default — ADR-0009);
+//   2. filename-discover `workflows/*.ts` (workflow name = filename, mirroring flue's
+//      `agents/<name>.ts`; module contract, ADR-0011 revised by ADR-0015: `export const machine`
+//      — the vocabulary rides the machine object via jr2Setup); register on the RunHost;
+//   3. `restore()` in-flight runs from the store (reconcile against the live world — ADR-0007);
+//   4. serve the hono HTTP surface (`createApp`) so the CLI / humans can push + control + observe.
+//
+// The one design point worth stating (ADR-0011 static-import doctrine): a workflow module is
+// self-contained — it declares its Agents and imports `gate` itself, in its own `setup` actors;
+// everything live is constructed per-invocation from serializable input (the flue client from
+// `input.endpoint`). The host injects NOTHING into workflow machines; `WorkflowDef.provide`
+// remains a seam for tests, not a wiring obligation.
+
+import { mkdir, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { AddressInfo } from "node:net";
+import { serve } from "@hono/node-server";
+import type { AnyStateMachine } from "xstate";
+import { createEchoPush } from "./harness-client.ts";
+import { createApp } from "./http.ts";
+import type { FetchAnswer } from "./repo-fetch.ts";
+import type { RepoStatus } from "./repos.ts";
+import { RunHost } from "./run-host.ts";
+import type { RunRecord } from "./run-host.ts";
+import { SqliteSnapshotStore } from "./snapshot-store.ts";
+import type { SnapshotStore } from "./snapshot-store.ts";
+import { createAuthenticator, loadSigningKey, mintInstanceToken } from "./tokens.ts";
+import type { SandboxPort } from "./workspace.ts";
+
+export type InstanceOptions = {
+  /** The instance folder (holds `workflows/`, and `.jr2/state.db` unless `store` is supplied). */
+  dir: string;
+  /** Listen port. Default 0 → an ephemeral port (read back from the running instance's `url`). */
+  port?: number;
+  /** Listen hostname. Default `127.0.0.1`. */
+  hostname?: string;
+  /** Override the durable store. Default: sqlite at `<dir>/.jr2/state.db`. */
+  store?: SnapshotStore;
+  /** Probe the live world before re-attaching on restore (ADR-0007). Default: always present. */
+  reconcile?: (run: RunRecord) => boolean | Promise<boolean>;
+  /** The Sandbox backend for `workspace()` workflows (ADR-0012). Composed by the caller — wired
+   * when a registered Machine composes a Sandbox and the process is deployed (ADR-0051); absent =
+   * an instance without a data plane, whose `workspace()` runs fault pointedly. */
+  sandbox?: SandboxPort;
+  /** Whether the instance has a data plane (ADR-0051) — what `GET /repos` reports beside the
+   * Repos, so `jr2 status` can say "no Workspace runs here" instead of listing nothing. */
+  dataPlane?: boolean;
+  /** The Repo resources as the cluster reports them (ADR-0051), read per request off the port the
+   * caller built. Absent = no data plane, which reports no Repos. */
+  repos?: () => Promise<RepoStatus[]>;
+  /** The ask a pod makes when something inside it fetches (ADR-0053), off the port the caller
+   * built. Absent = no data plane, so no Sandbox to ask for. */
+  fetchRepo?: (sandbox: string, identity: string) => Promise<FetchAnswer>;
+  /** The Instance Harness base URL (ADR-0031) — where a `workspace: "none"` Turn is admitted.
+   * The entrypoint derives it from the pod's namespace (deterministic Service DNS); absent,
+   * such a Turn without an explicit `endpoint` faults pointedly. */
+  instanceHarness?: string;
+  /** The key Sandbox tokens are signed with (ADR-0013). Default: `<dir>/.jr2/secret`, minted on
+   * first boot. Supply it when the instance folder must stay untouched (tests), or when the same
+   * key must reach a `kubectlSandbox` built before this call (it mints the tokens). */
+  signingKey?: Buffer;
+  /** The Instance token to authenticate with (ADR-0013/0019). Deployed, `jr2 up` materializes it in
+   * the instance's Secret and the entrypoint passes it here, so a pod restart keeps the credential
+   * the CLI reads from that Secret. Default: minted per boot. */
+  instanceToken?: string;
+};
+
+/** What changed on a `reload()` — the diff against the previously-registered set. */
+export type ReloadResult = { added: string[]; updated: string[]; removed: string[]; workflows: string[] };
+
+export type RunningInstance = {
+  host: RunHost;
+  /** The base URL the HTTP surface is reachable at (with the resolved port). */
+  url: string;
+  /**
+   * The Instance token this boot serves under (ADR-0013): the credential for gates and run
+   * control. Deployed it is supplied from the instance's Secret (ADR-0019) so it survives pod
+   * restarts; when minted per boot instead, only this handle knows it. The SIGNING KEY behind the
+   * Sandbox tokens must never rotate per boot either way (see `loadSigningKey`).
+   */
+  instanceToken: string;
+  /** Names of the workflows discovered + registered from `<dir>/workflows`. */
+  workflows: string[];
+  /** What this boot did with the runs it found persisted (ADR-0007, ADR-0030) — resumed, given up
+   * on, refused because their Machine changed shape, or errored (left for the next boot to retry).
+   * The entrypoint announces everything but the resumed ones. */
+  restored: { reattached: string[]; lost: string[]; drifted: string[]; failed: string[] };
+  /**
+   * Re-discover `<dir>/workflows` and re-register every file, replacing changed definitions and
+   * dropping deleted ones. A dev/test-only affordance — the deployed entrypoint ships workflows
+   * baked into its image and never reloads. In-flight runs keep the
+   * definition they started on; only the next `start` sees new code (ADR-0009).
+   */
+  reload: () => Promise<ReloadResult>;
+  /** Stop the HTTP server and close the store. */
+  close: () => Promise<void>;
+};
+
+/** Boot an instance folder into a running orchestrator (discover → restore → serve). */
+export async function startInstance(opts: InstanceOptions): Promise<RunningInstance> {
+  const hostname = opts.hostname ?? "127.0.0.1";
+
+  // 1. Durable store. Default sqlite needs its parent dir to exist before `DatabaseSync` opens it.
+  let store = opts.store;
+  if (!store) {
+    await mkdir(join(opts.dir, ".jr2"), { recursive: true });
+    store = new SqliteSnapshotStore(join(opts.dir, ".jr2", "state.db"));
+  }
+  await store.init();
+
+  // Resolved BEFORE the host: the Instance token is also the echo bearer (ADR-0023), so the
+  // host's echo pusher closes over it. Served under in step 4 below, unchanged.
+  const instanceToken = opts.instanceToken ?? mintInstanceToken();
+
+  const host = new RunHost({
+    store,
+    reconcile: opts.reconcile,
+    sandbox: opts.sandbox,
+    instanceHarness: opts.instanceHarness,
+    // The run-narrative echo (ADR-0023): tee a run's feed to its enclosing Workspace's Harness,
+    // authenticated as the instance. The wire push is here and the fire-and-forget is the
+    // host's, so a Harness that refuses (or is gone) costs a log line at most.
+    echo: (endpoint) => createEchoPush({ baseUrl: endpoint, token: instanceToken }),
+    // A run left `live` to be retried is otherwise unexplained — the announce line names it, this
+    // says why (ADR-0030). stderr, because it is a fault, not the boot's structured result.
+    onRestoreError: (runId, err) =>
+      console.error(`restore failed for run ${runId}: ${err instanceof Error ? err.message : err}`),
+  });
+
+  // Bump per reload so `import()` re-reads a changed file rather than serving the ESM module cache.
+  let importGen = 0;
+  const registerFile = async (name: string, file: string): Promise<void> => {
+    const machine = await importMachine(name, file, importGen);
+    host.register({
+      name,
+      machine,
+      // Nothing to inject (ADR-0011): the module imports its own actors; live clients are built
+      // per-invocation from input. `provide` stays a test seam on WorkflowDef, unused here.
+      provide: () => ({}),
+    });
+  };
+
+  // 2. Filename discovery: every `workflows/<name>.ts` exports its Machine + event manifest by name.
+  for (const { name, file } of await discoverWorkflows(opts.dir)) await registerFile(name, file);
+
+  // 3. Resume in-flight runs persisted by a prior process (ADR-0007). The outcome is reported, not
+  // swallowed (ADR-0030): a boot that declined to resume runs must say so, or "drifted" is only
+  // discoverable by asking after a specific run id nobody knows to ask about.
+  const restored = await host.restore();
+
+  // 4. Serve, authenticated (ADR-0013). The signing key is loaded from (or minted into) the
+  // instance folder, NOT generated per process: live Sandboxes outlive a restart, and their
+  // Adapters still bear tokens this key signed. The Instance token is per-boot; the key is not.
+  const signingKey = opts.signingKey ?? (await loadSigningKey(opts.dir));
+  const auth = createAuthenticator({ instanceToken, signingKey });
+  // The Repos are read PER REQUEST, never snapshotted here: a cache the agent cloned minutes
+  // after boot must show as present the next time anyone asks (ADR-0048/0051).
+  const app = createApp(host, auth, { dataPlane: opts.dataPlane, repos: opts.repos, fetchRepo: opts.fetchRepo });
+  const server = serve({ fetch: app.fetch, port: opts.port ?? 0, hostname });
+  const port = await new Promise<number>((resolve) => {
+    server.once("listening", () => resolve((server.address() as AddressInfo).port));
+  });
+
+  return {
+    host,
+    url: `http://${hostname}:${port}`,
+    instanceToken,
+    workflows: host.workflows(),
+    restored,
+    reload: async () => {
+      importGen++;
+      const before = new Set(host.workflows());
+      const found = await discoverWorkflows(opts.dir);
+      const foundNames = new Set(found.map((f) => f.name));
+      for (const { name, file } of found) await registerFile(name, file);
+      const removed: string[] = [];
+      for (const name of before) if (!foundNames.has(name)) (host.unregister(name), removed.push(name));
+      const added = [...foundNames].filter((n) => !before.has(n));
+      const updated = [...foundNames].filter((n) => before.has(n));
+      return { added, updated, removed, workflows: host.workflows() };
+    },
+    close: async () => {
+      // Before `server.close()`, not after: it waits for in-flight requests, and an observation
+      // feed is in-flight until its watcher goes away. `host.close()` is what makes them go away.
+      await host.close();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await store.close();
+    },
+  };
+}
+
+/** List `<dir>/workflows/*.ts` (ignoring `_`-prefixed helpers + `.d.ts`); name = filename stem. */
+async function discoverWorkflows(dir: string): Promise<Array<{ name: string; file: string }>> {
+  // An absent workflows/ dir → an instance with no workflows yet (still boots + serves).
+  return discoverModules(join(dir, "workflows"));
+}
+
+/** Import one workflow module and take its Machine — the module contract (ADR-0011/0015):
+ * `export const machine`. `gen` cache-busts a reload; 0 imports the module URL untouched. */
+async function importMachine(name: string, file: string, gen = 0): Promise<AnyStateMachine> {
+  const href = pathToFileURL(file).href + (gen ? `?v=${gen}` : "");
+  const mod: { machine?: unknown } = await import(href);
+  const machine = mod.machine as AnyStateMachine | undefined;
+  if (!machine) {
+    throw new Error(
+      `workflow "${name}" (${file}) has no \`machine\` named export ` +
+        `(module contract, ADR-0011/0015: \`export const machine\`)`,
+    );
+  }
+  return machine;
+}
+
+/**
+ * Discover + load every Workflow an instance folder registers — the same discovery and the same
+ * module contract `startInstance` boots with, without booting.
+ *
+ * `jr2 up` is the caller (ADR-0049/0050): a Machine carries its Agents and its Sandbox Image, so
+ * the only way to know what a deployment must preflight and converge is to load the Machines and
+ * WALK them (`partsOf`, parts.ts). It lives here, beside the discovery it shares, so the
+ * convention has one implementation rather than a second copy in the CLI that can drift.
+ */
+export async function loadWorkflows(dir: string): Promise<Array<{ name: string; machine: AnyStateMachine }>> {
+  const loaded: Array<{ name: string; machine: AnyStateMachine }> = [];
+  for (const { name, file } of await discoverWorkflows(dir)) {
+    loaded.push({ name, machine: await importMachine(name, file) });
+  }
+  return loaded;
+}
+
+/**
+ * The instance module-discovery convention: every `<moduleDir>/<name>.ts` except `_`-prefixed
+ * helpers and `.d.ts`, sorted, name = filename stem. `workflows/` is the one directory that uses
+ * it, and the ONLY thing an Instance still discovers by filename (ADR-0050: what only the CLI and
+ * the HTTP API name is discovered; everything code names rides the Machine). The `agents/` folder
+ * and the `images/<name>` dirname scan it was also written for both retired with ADR-0049. An
+ * ABSENT dir is empty; any other readdir failure (EACCES, ENOTDIR, …) throws — a directory that
+ * exists but cannot be read must be loud, never "no modules".
+ */
+export async function discoverModules(moduleDir: string): Promise<Array<{ name: string; file: string }>> {
+  let entries: string[];
+  try {
+    entries = await readdir(moduleDir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+  return entries
+    .filter((f) => f.endsWith(".ts") && !f.endsWith(".d.ts") && !f.startsWith("_"))
+    .sort()
+    .map((f) => ({ name: f.slice(0, -3), file: join(moduleDir, f) }));
+}
+
+/**
+ * The Instance's `images/default` build context, or undefined when it scaffolded none — ADR-0037's
+ * middle resolution leg, so that a local Machine never has to spell
+ * `import.meta.resolve("../images/default")` for the toolchain its own instance ships.
+ *
+ * A PATH CONVENTION, not discovery (ADR-0049/0050). There is exactly one path, it is checked, and
+ * nothing is enumerated: `images/<name>` dirnames stopped being names the moment a Machine started
+ * carrying its own image, and a folder scan would re-introduce the very thing that made a packaged
+ * Machine depend on someone else's directory layout. A second image is a `file:` context beside the
+ * Machine that names it.
+ *
+ * A folder with no `Dockerfile` THROWS, naming the missing path: unlike a stray `README.md`,
+ * `images/default/` has no other reason to exist, so silence there would be a Sandbox Image the
+ * author believes in and no converge ever builds.
+ *
+ * The Orchestrator process never calls this — refs reach it resolved, through the `jr2-images`
+ * ConfigMap (images.ts). It lives here because it is an Instance-layout fact, beside the one
+ * discovery convention that survives.
+ */
+export async function defaultImageContext(dir: string): Promise<string | undefined> {
+  const imageDir = join(dir, "images", "default");
+  try {
+    await stat(join(imageDir, "Dockerfile"));
+    return imageDir;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+  try {
+    await stat(imageDir);
+  } catch {
+    return undefined;
+  }
+  throw new Error(
+    `the Instance's \`images/default\` has no Dockerfile (${join(imageDir, "Dockerfile")}) — that directory IS ` +
+      "a build context (ADR-0037), and it is the Sandbox Image every `workspace()` that names none falls back to.",
+  );
+}