@nanobpm/agentic 0.1.0

package/src/cockpit/boot.test.ts

@@ -0,0 +1,374 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { decodeFrame, encodeFrame, type Frame } from "../protocol/index.ts";
+import type { DemandSupplyReport } from "../demand/index.ts";
+
+import { bootCockpit, type CockpitEnv } from "./boot.ts";
+import { FakeDocument, FakeElement } from "./fake-dom.ts";
+import type { RawSocket } from "./relay-client.ts";
+
+class FakeSocket implements RawSocket {
+  readonly sent: Uint8Array[] = [];
+  closed = false;
+  #onMessage: ((bytes: Uint8Array) => void) | undefined;
+  #onOpen: (() => void) | undefined;
+  #onClose: (() => void) | undefined;
+  send(bytes: Uint8Array): void {
+    this.sent.push(bytes);
+  }
+  close(): void {
+    this.closed = true;
+  }
+  onMessage(l: (bytes: Uint8Array) => void): void {
+    this.#onMessage = l;
+  }
+  onOpen(l: () => void): void {
+    this.#onOpen = l;
+  }
+  onClose(l: () => void): void {
+    this.#onClose = l;
+  }
+  fireOpen(): void {
+    this.#onOpen?.();
+  }
+  fireClose(): void {
+    this.#onClose?.();
+  }
+  deliver(frame: Frame): void {
+    this.#onMessage?.(encodeFrame(frame));
+  }
+  subscribeFrames(): Frame[] {
+    return this.sent.map(decodeFrame).filter((f) => f.family === "relay");
+  }
+}
+
+const flush = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+function reportWith(networks: DemandSupplyReport["networks"], missing: string[] = []): DemandSupplyReport {
+  return {
+    networks,
+    missing,
+    diversity: { status: "green", roles: [] },
+    status: missing.length > 0 ? "red" : "green",
+    nonAgentic: [],
+  };
+}
+
+const served = reportWith([
+  { network: "ci", tokens: [{ token: "ci.build", supply: 1, instances: ["ci-a"], satisfied: true }], missing: [] },
+]);
+
+interface Rig {
+  readonly env: CockpitEnv;
+  readonly host: FakeElement;
+  readonly sockets: FakeSocket[];
+  readonly terminalWrites: string[];
+  terminalMounts: number;
+  terminalDisposes: number;
+  readonly timers: Array<{ run: () => void; ms: number }>;
+  reconnect: (() => void) | undefined;
+  report: DemandSupplyReport;
+  errors: unknown[];
+}
+
+function rig(): Rig {
+  const host = new FakeElement("body");
+  const sockets: FakeSocket[] = [];
+  const terminalWrites: string[] = [];
+  const timers: Array<{ run: () => void; ms: number }> = [];
+  const state: Rig = {
+    host,
+    sockets,
+    terminalWrites,
+    terminalMounts: 0,
+    terminalDisposes: 0,
+    timers,
+    reconnect: undefined,
+    report: served,
+    errors: [],
+    env: {
+      host,
+      doc: new FakeDocument(),
+      fetchReport: () => Promise.resolve(state.report),
+      connectRelay: () => {
+        const s = new FakeSocket();
+        sockets.push(s);
+        return s;
+      },
+      createTerminal: (terminalHost) => {
+        state.terminalMounts += 1;
+        terminalHost.appendChild(new FakeElement("pre"));
+        return {
+          write: (chunk) => terminalWrites.push(chunk),
+          dispose: () => {
+            state.terminalDisposes += 1;
+          },
+        };
+      },
+      schedule: (run) => {
+        state.reconnect = run;
+      },
+      setTimer: (run, ms) => {
+        timers.push({ run, ms });
+        return timers.length - 1;
+      },
+      clearTimer: () => {},
+      onError: (err) => state.errors.push(err),
+    },
+  };
+  return state;
+}
+
+test("refresh renders the live demand×supply matrix into the host", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+  assert.equal(r.host.byData("network", "ci").length, 1);
+  assert.equal(r.host.byClass("cockpit-token").length, 1);
+});
+
+test("a later poll reflects a changed report (a newly missing agent type lights red)", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+  assert.equal(r.host.byClass("cockpit-network")[0]?.getAttribute("data-status"), "green");
+
+  r.report = reportWith(
+    [
+      {
+        network: "ci",
+        tokens: [{ token: "ci.build", supply: 0, instances: [], satisfied: false }],
+        missing: ["ci.build"],
+      },
+    ],
+    ["ci.build"],
+  );
+  await cockpit.refresh();
+  assert.equal(r.host.byData("network", "ci")[0]?.getAttribute("data-status"), "red");
+  const missing = r.host.byClass("cockpit-light").filter((l) => l.getAttribute("data-light-id")?.startsWith("missing:"));
+  assert.equal(missing.length, 1);
+});
+
+test("drilling into a worker subscribes its relay stream on connect", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("ci-a");
+  assert.equal(cockpit.currentStream, "ci-a");
+  assert.equal(r.sockets.length, 1);
+
+  r.sockets[0]?.fireOpen(); // (re)connect → session.attach()
+  const subs = r.sockets[0]?.subscribeFrames() ?? [];
+  assert.equal(subs.length, 1);
+  assert.deepEqual(subs[0]?.payload, { op: "subscribe", stream: "ci-a", from: 0, credit: 1024 });
+});
+
+test("relay output is written to the drilled worker's terminal", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("ci-a");
+  r.sockets[0]?.fireOpen();
+  r.sockets[0]?.deliver({ lane: "bulk", family: "relay", seq: 0, payload: { stream: "ci-a", offset: 0, chunk: "boot\n" } });
+  assert.deepEqual(r.terminalWrites, ["boot\n"]);
+});
+
+test("the terminal survives a matrix refresh — it is not re-mounted and keeps streaming", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("ci-a");
+  r.sockets[0]?.fireOpen();
+  r.sockets[0]?.deliver({ lane: "bulk", family: "relay", seq: 0, payload: { stream: "ci-a", offset: 0, chunk: "a" } });
+
+  await cockpit.refresh(); // a poll re-renders the matrix
+  assert.equal(r.terminalMounts, 1, "the terminal was not re-mounted by the refresh");
+
+  r.sockets[0]?.deliver({ lane: "bulk", family: "relay", seq: 1, payload: { stream: "ci-a", offset: 1, chunk: "b" } });
+  assert.deepEqual(r.terminalWrites, ["a", "b"]);
+});
+
+test("the terminal survives a cockpit reconnect — resume-from-offset, no loss, no dup", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("ci-a");
+
+  const s1 = r.sockets[0];
+  s1?.fireOpen();
+  s1?.deliver({ lane: "bulk", family: "relay", seq: 0, payload: { stream: "ci-a", offset: 0, chunk: "a" } });
+  s1?.deliver({ lane: "bulk", family: "relay", seq: 1, payload: { stream: "ci-a", offset: 1, chunk: "b" } });
+
+  // The cockpit's socket drops; the client schedules a reconnect.
+  s1?.fireClose();
+  assert.ok(r.reconnect !== undefined, "a reconnect was scheduled");
+  r.reconnect?.();
+  assert.equal(r.sockets.length, 2, "a fresh socket was opened");
+
+  const s2 = r.sockets[1];
+  s2?.fireOpen(); // re-attach → resume from offset 2
+  const subs = s2?.subscribeFrames() ?? [];
+  assert.deepEqual(subs.at(-1)?.payload, { op: "subscribe", stream: "ci-a", from: 2, credit: 1024 });
+
+  // The hub replays the retained tail (re-sends 1) then continues.
+  s2?.deliver({ lane: "bulk", family: "relay", seq: 0, payload: { stream: "ci-a", offset: 1, chunk: "b" } });
+  s2?.deliver({ lane: "bulk", family: "relay", seq: 1, payload: { stream: "ci-a", offset: 2, chunk: "c" } });
+  assert.deepEqual(r.terminalWrites, ["a", "b", "c"], "no lost and no duplicated output across reconnect");
+});
+
+test("drilling the same stream twice does not re-open; a different stream switches", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("ci-a");
+  cockpit.drill("ci-a");
+  assert.equal(r.sockets.length, 1);
+  assert.equal(r.terminalMounts, 1);
+
+  cockpit.drill("ci-b");
+  assert.equal(r.sockets[0]?.closed, true, "the previous connection was closed");
+  assert.equal(r.sockets.length, 2);
+  assert.equal(r.terminalMounts, 2);
+  assert.equal(cockpit.currentStream, "ci-b");
+});
+
+test("a synchronous failure building a new drill is reported and leaves no stale current stream", async () => {
+  const r = rig();
+  let mounts = 0;
+  const flaky: CockpitEnv = {
+    ...r.env,
+    createTerminal: (terminalHost) => {
+      mounts += 1;
+      // The second drill's terminal fails to build.
+      if (mounts === 2) throw new Error("terminal boom");
+      return r.env.createTerminal(terminalHost);
+    },
+  };
+  const cockpit = bootCockpit(flaky);
+  await cockpit.refresh();
+
+  cockpit.drill("ci-a");
+  assert.equal(cockpit.currentStream, "ci-a");
+  assert.equal(r.sockets.length, 1);
+
+  // Switching streams: building the new drill throws synchronously. The prior
+  // client is still closed, the error is routed to onError, and currentStream
+  // reports no live drill — never the stale, already-closed "ci-a".
+  cockpit.drill("ci-b");
+  assert.equal(r.sockets[0]?.closed, true, "the previous connection was closed");
+  assert.equal(r.sockets.length, 1, "no socket opened for the failed drill");
+  assert.equal(cockpit.currentStream, undefined, "no stale current stream after a failed drill");
+  assert.match(String(r.errors.at(-1)), /terminal boom/);
+});
+
+test("an invalid credit fails the drill into onError instead of escaping the handler", async () => {
+  const r = rig();
+  const badCredit: CockpitEnv = { ...r.env, credit: 0 };
+  const cockpit = bootCockpit(badCredit);
+  await cockpit.refresh();
+
+  // TerminalSession construction rejects a non-positive credit; the throw is
+  // caught, routed to onError, and no drill/socket is left dangling.
+  cockpit.drill("ci-a");
+  assert.equal(cockpit.currentStream, undefined);
+  assert.equal(r.sockets.length, 0, "connect never ran, so no socket was opened");
+  assert.match(String(r.errors.at(-1)), /credit must be a positive safe integer/);
+});
+
+test("start runs a pass and self-schedules the next; stop halts it", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  cockpit.start();
+  await flush();
+  assert.equal(r.host.byData("network", "ci").length, 1, "first pass rendered");
+  assert.equal(r.timers.length, 1, "next pass scheduled once");
+
+  r.timers[0]?.run(); // fire the scheduled tick
+  await flush();
+  assert.equal(r.timers.length, 2, "a subsequent pass was scheduled");
+
+  cockpit.stop();
+  const before = r.timers.length;
+  await flush();
+  assert.equal(r.timers.length, before, "no further passes after stop");
+});
+
+test("a fetch error is reported and does not wedge the poll", async () => {
+  const r = rig();
+  const failing: CockpitEnv = { ...r.env, fetchReport: () => Promise.reject(new Error("boom")) };
+  const cockpit = bootCockpit(failing);
+  await cockpit.refresh();
+  assert.equal(r.errors.length, 1);
+});
+
+test("dispose stops polling and closes the terminal connection", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("ci-a");
+  cockpit.dispose();
+  assert.equal(r.sockets[0]?.closed, true);
+});
+
+test("injecting setTimer without clearTimer (or vice versa) fails fast", () => {
+  const base = rig().env;
+  const noop = () => 0;
+  assert.throws(
+    () => bootCockpit({ ...base, setTimer: noop, clearTimer: undefined }),
+    /setTimer and clearTimer must be provided together/,
+  );
+  assert.throws(
+    () => bootCockpit({ ...base, setTimer: undefined, clearTimer: () => {} }),
+    /setTimer and clearTimer must be provided together/,
+  );
+});
+
+test("an invalid refreshMs fails fast at construction", () => {
+  const base = rig().env;
+  for (const refreshMs of [0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1, Number.NaN]) {
+    assert.throws(
+      () => bootCockpit({ ...base, refreshMs }),
+      /refreshMs must be a positive safe integer/,
+      `refreshMs ${refreshMs} should be rejected`,
+    );
+  }
+});
+
+test("switching streams disposes the prior terminal, and dispose tears the last one down", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+
+  cockpit.drill("ci-a");
+  assert.equal(r.terminalMounts, 1);
+  assert.equal(r.terminalDisposes, 0, "nothing to dispose on the first drill");
+
+  // Switching streams must tear down the previous xterm instance before mounting
+  // the next — replaceChildren only drops the DOM node, so without an explicit
+  // dispose the widget + its listeners would leak on every drill.
+  cockpit.drill("ci-b");
+  assert.equal(r.terminalMounts, 2);
+  assert.equal(r.terminalDisposes, 1, "prior terminal disposed on stream switch");
+
+  cockpit.dispose();
+  assert.equal(r.terminalDisposes, 2, "the live terminal is disposed on dispose()");
+});
+
+test("a stop→start race does not leave two overlapping poll chains scheduling", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+
+  // First start's tick has an in-flight refresh (suspended at the fetch await),
+  // whose finally has not run yet. Stopping then restarting before it settles
+  // must invalidate that stale tick so only the new start's chain schedules —
+  // otherwise the stale finally re-arms a second, overlapping timer.
+  cockpit.start();
+  cockpit.stop();
+  cockpit.start();
+  await flush();
+
+  assert.equal(r.timers.length, 1, "exactly one poll chain scheduled after the race");
+
+  cockpit.stop();
+});

package/src/cockpit/boot.ts

@@ -0,0 +1,280 @@
+/**
+ * The cockpit boot/orchestration layer — S8.
+ *
+ * Wires the whole page together from injected capabilities, with **no** direct
+ * dependency on the browser, a socket implementation, or xterm.js — everything is
+ * passed in ({@link CockpitEnv}). That is what makes the page render *identically*
+ * embedded (console App View) and standalone (the two shells differ only in the
+ * `host` element and the concrete capabilities they inject), and what makes the
+ * live-refresh + drill-in + resume-on-reconnect path unit-testable on Node.
+ *
+ * Responsibilities:
+ *  - a **self-scheduling** poll of the S4 demand×supply report that re-renders the
+ *    matrix/lights each pass (a slow fetch can't overlap the next — mirrors the
+ *    nano-workforce poller discipline);
+ *  - **drill-into-a-worker**: open a {@link RelayChannelClient} + {@link TerminalSession}
+ *    for the selected stream, mount its output into a *persistent* terminal region
+ *    (so a matrix refresh never wipes it), and re-attach on every reconnect so the
+ *    terminal **survives a cockpit reconnect** via resume-from-offset.
+ */
+import type { DemandSupplyReport } from "../demand/index.ts";
+import { isPosInt } from "../relay/index.ts";
+import { RelayChannelClient, type Scheduler, type SocketFactory } from "./relay-client.ts";
+import { type DocumentLike, type ElementLike, renderCockpit } from "./render.ts";
+import { TerminalSession, type TerminalSink } from "./terminal-session.ts";
+import { cockpitView } from "./view.ts";
+
+/** Mounts a terminal into `host` and returns the sink relay output is written to. */
+export type CreateTerminal = (host: ElementLike) => TerminalSink;
+
+/** An opaque poll-timer handle (a Node `Timeout` or a browser timer id). */
+export type TimerHandle = unknown;
+
+export interface CockpitEnv {
+  /** The element the cockpit renders into (standalone: `document.body`; embedded: the App View host). */
+  readonly host: ElementLike;
+  /** The document the renderer creates elements from. */
+  readonly doc: DocumentLike;
+  /** Fetches the latest S4 demand×supply report (e.g. over HTTP or the channel). */
+  readonly fetchReport: () => Promise<DemandSupplyReport>;
+  /** Opens a socket to the app relay channel (one per drill-in connection). */
+  readonly connectRelay: SocketFactory;
+  /** Mounts the terminal widget (xterm.js in the browser) and returns its write sink. */
+  readonly createTerminal: CreateTerminal;
+  /** Reconnect scheduler for the relay client. Default `setTimeout(run, 0)`. */
+  readonly schedule?: Scheduler;
+  /** Poll scheduler. Default `setTimeout`. Injected so tests drive it by hand. Must be paired with {@link clearTimer}. */
+  readonly setTimer?: (run: () => void, ms: number) => TimerHandle;
+  /** Cancels a poll timer. Default `clearTimeout`. Must be paired with {@link setTimer}. */
+  readonly clearTimer?: (handle: TimerHandle) => void;
+  /** Poll interval in ms. Default 2000. */
+  readonly refreshMs?: number;
+  /** Bulk credit granted per terminal (re)subscribe. Default 1024. */
+  readonly credit?: number;
+  /** Notified of a fetch/render/relay error (the poll keeps going). */
+  readonly onError?: (err: unknown) => void;
+}
+
+/** The running cockpit; dispose to stop polling and tear down the terminal. */
+export interface CockpitHandle {
+  /** Run one fetch→render pass now (also the poll body). Resolves when rendered. */
+  refresh(): Promise<void>;
+  /** Start the self-scheduling poll loop (runs one pass immediately). */
+  start(): void;
+  /** Stop the poll loop (leaves the last render in place). */
+  stop(): void;
+  /** Drill into a worker's relay stream, opening a resumable live terminal. */
+  drill(stream: string): void;
+  /** The stream currently drilled into, if any. */
+  readonly currentStream: string | undefined;
+  /** Stop everything and release the terminal connection. */
+  dispose(): void;
+}
+
+const DEFAULT_REFRESH_MS = 2000;
+
+interface Drill {
+  readonly stream: string;
+  readonly client: RelayChannelClient;
+}
+
+class Cockpit implements CockpitHandle {
+  readonly #env: CockpitEnv;
+  readonly #matrixRegion: ElementLike;
+  readonly #terminalHost: ElementLike;
+  readonly #refreshMs: number;
+  readonly #setTimer: (run: () => void, ms: number) => TimerHandle;
+  readonly #clearTimer: (handle: TimerHandle) => void;
+  readonly #timeouts = new Map<number, ReturnType<typeof setTimeout>>();
+  #nextTimerId = 0;
+  #timer: TimerHandle | undefined;
+  #running = false;
+  #disposed = false;
+  #drill: Drill | undefined;
+  // The currently mounted terminal, tracked so switching streams (and dispose)
+  // tears down the prior xterm instance instead of leaking it + its listeners.
+  #terminal: TerminalSink | undefined;
+  // Bumped by every start()/stop() so an in-flight #tick() from a previous
+  // start cycle can't reschedule after a stop→start race and leave two
+  // overlapping poll chains running against the same cockpit.
+  #generation = 0;
+
+  constructor(env: CockpitEnv) {
+    this.#env = env;
+    this.#refreshMs = env.refreshMs ?? DEFAULT_REFRESH_MS;
+    // refreshMs feeds setTimeout as a poll delay. A negative/NaN/fractional/unsafe
+    // value silently collapses to a ~0ms delay, turning the poll into a hot loop
+    // that hammers the demand endpoint and burns CPU. Require a positive safe
+    // integer up-front so a bad env option fails loudly instead.
+    if (!isPosInt(this.#refreshMs)) {
+      throw new RangeError(`CockpitEnv.refreshMs must be a positive safe integer, got ${this.#refreshMs}`);
+    }
+    // setTimer/clearTimer are a matched pair: a caller-supplied setTimer returns
+    // opaque handles the default clearTimer (which only understands the internal
+    // numeric-handle Map) cannot cancel, leaving an un-stoppable poll loop. Fail
+    // fast rather than silently accept one without the other.
+    if ((env.setTimer === undefined) !== (env.clearTimer === undefined)) {
+      throw new Error("CockpitEnv.setTimer and clearTimer must be provided together (or neither)");
+    }
+    // Default timer path uses numeric handles backed by a Map, so no unchecked
+    // cast is needed to feed an opaque handle back to clearTimeout (`as` is banned).
+    this.#setTimer =
+      env.setTimer ??
+      ((run, ms) => {
+        const id = this.#nextTimerId++;
+        this.#timeouts.set(
+          id,
+          setTimeout(() => {
+            this.#timeouts.delete(id);
+            run();
+          }, ms),
+        );
+        return id;
+      });
+    this.#clearTimer =
+      env.clearTimer ??
+      ((handle) => {
+        if (typeof handle !== "number") return;
+        const timeout = this.#timeouts.get(handle);
+        if (timeout !== undefined) {
+          clearTimeout(timeout);
+          this.#timeouts.delete(handle);
+        }
+      });
+
+    // Build the stable skeleton once: a volatile matrix region the poll
+    // re-renders, and a PERSISTENT terminal region a refresh never touches.
+    env.host.replaceChildren();
+    const shell = env.doc.createElement("div");
+    shell.className = "cockpit-shell";
+    this.#matrixRegion = env.doc.createElement("div");
+    this.#matrixRegion.className = "cockpit-matrix-region";
+    const terminalPanel = env.doc.createElement("section");
+    terminalPanel.className = "cockpit-terminal";
+    const title = env.doc.createElement("h2");
+    title.className = "cockpit-panel-title";
+    title.textContent = "Worker terminal";
+    terminalPanel.appendChild(title);
+    this.#terminalHost = env.doc.createElement("div");
+    this.#terminalHost.className = "cockpit-terminal-host";
+    this.#terminalHost.setAttribute("data-terminal", "host");
+    terminalPanel.appendChild(this.#terminalHost);
+    shell.appendChild(this.#matrixRegion);
+    shell.appendChild(terminalPanel);
+    env.host.appendChild(shell);
+  }
+
+  get currentStream(): string | undefined {
+    return this.#drill?.stream;
+  }
+
+  async refresh(): Promise<void> {
+    if (this.#disposed) return;
+    let report: DemandSupplyReport;
+    try {
+      report = await this.#env.fetchReport();
+    } catch (err) {
+      this.#env.onError?.(err);
+      return;
+    }
+    if (this.#disposed) return;
+    try {
+      renderCockpit(this.#matrixRegion, this.#env.doc, cockpitView(report), {
+        onDrill: (stream) => this.drill(stream),
+      });
+    } catch (err) {
+      this.#env.onError?.(err);
+    }
+  }
+
+  start(): void {
+    if (this.#disposed || this.#running) return;
+    this.#running = true;
+    const generation = ++this.#generation;
+    this.#tick(generation);
+  }
+
+  stop(): void {
+    this.#running = false;
+    // Invalidate any in-flight tick so its finally can't reschedule after this.
+    this.#generation++;
+    if (this.#timer !== undefined) {
+      this.#clearTimer(this.#timer);
+      this.#timer = undefined;
+    }
+  }
+
+  #tick(generation: number): void {
+    // Self-scheduling: schedule the NEXT pass only after this one settles, so a
+    // slow fetch can never overlap its successor. The generation guard drops a
+    // stale tick whose start cycle was already stopped (and possibly restarted),
+    // so a stop→start race never leaves two poll chains scheduling in parallel.
+    void this.refresh().finally(() => {
+      if (generation !== this.#generation || !this.#running || this.#disposed) return;
+      this.#timer = this.#setTimer(() => this.#tick(generation), this.#refreshMs);
+    });
+  }
+
+  drill(stream: string): void {
+    if (this.#disposed) return;
+    if (this.#drill?.stream === stream) return;
+    // Close and drop the prior drill up-front so a synchronous failure while
+    // building the new one (e.g. createTerminal, an invalid TerminalSession
+    // credit, or connect throwing) can't leave #drill pointing at an
+    // already-closed client — currentStream would then report a dead stream.
+    // #drill is re-set only once the new client is fully wired and opened, so
+    // state stays consistent even when the new drill fails to initialize; the
+    // failure is routed to onError like every other relay/terminal error.
+    this.#drill?.client.close();
+    this.#drill = undefined;
+    // Tear down the prior terminal before mounting a fresh one so repeated
+    // drills don't leak xterm instances/listeners (replaceChildren only drops
+    // the DOM node, not the widget). Tracked in #terminal so a failed (re)drill
+    // still cleans it up on the next drill or on dispose().
+    this.#terminal?.dispose?.();
+    this.#terminal = undefined;
+
+    try {
+      // Fresh terminal for the newly selected worker.
+      this.#terminalHost.replaceChildren();
+      const sink = this.#env.createTerminal(this.#terminalHost);
+      this.#terminal = sink;
+
+      let session: TerminalSession | undefined;
+      const client = new RelayChannelClient({
+        connect: this.#env.connectRelay,
+        onRelay: (message) => session?.handle(message),
+        // Re-attach on EVERY (re)connect → resume-from-offset: the terminal
+        // survives a cockpit reconnect without losing or double-writing output.
+        onOpen: () => session?.attach(),
+        schedule: this.#env.schedule,
+        onError: (err) => this.#env.onError?.(err),
+      });
+      session = new TerminalSession({
+        stream,
+        sink,
+        send: (message) => client.sendRelay(message),
+        credit: this.#env.credit,
+      });
+      client.open();
+      this.#drill = { stream, client };
+    } catch (err) {
+      this.#env.onError?.(err);
+    }
+  }
+
+  dispose(): void {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    this.stop();
+    this.#drill?.client.close();
+    this.#drill = undefined;
+    this.#terminal?.dispose?.();
+    this.#terminal = undefined;
+  }
+}
+
+/** Boot the cockpit against an injected environment. Call {@link CockpitHandle.start} to poll. */
+export function bootCockpit(env: CockpitEnv): CockpitHandle {
+  return new Cockpit(env);
+}