@nanobpm/nano-workforce 0.54.0 → 0.56.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.56.0](https://github.com/nanobpm/nano-workforce/compare/v0.55.0...v0.56.0) (2026-08-13)
+
+
+### Features
+
+* correlate jobKeys to process/plan across supply report + cockpit (H6) ([#182](https://github.com/nanobpm/nano-workforce/issues/182)) ([f6e2b0d](https://github.com/nanobpm/nano-workforce/commit/f6e2b0d5f804c4c30863e5f5c66bbdc835025046)), closes [#142](https://github.com/nanobpm/nano-workforce/issues/142) [#152](https://github.com/nanobpm/nano-workforce/issues/152) [#149](https://github.com/nanobpm/nano-workforce/issues/149)
+
+# [0.55.0](https://github.com/nanobpm/nano-workforce/compare/v0.54.0...v0.55.0) (2026-08-13)
+
+
+### Features
+
+* supply-only agentic cockpit page + report endpoint (H5) ([#173](https://github.com/nanobpm/nano-workforce/issues/173)) ([428f7f3](https://github.com/nanobpm/nano-workforce/commit/428f7f3a8ca35ea05c8b9c0dbc478d24d125486a)), closes [#144](https://github.com/nanobpm/nano-workforce/issues/144) [#146](https://github.com/nanobpm/nano-workforce/issues/146) [#152](https://github.com/nanobpm/nano-workforce/issues/152) [#148](https://github.com/nanobpm/nano-workforce/issues/148) [#144](https://github.com/nanobpm/nano-workforce/issues/144) [#146](https://github.com/nanobpm/nano-workforce/issues/146)
+
 # [0.54.0](https://github.com/nanobpm/nano-workforce/compare/v0.53.0...v0.54.0) (2026-08-13)
 
 

package/app/agentic/cockpit/index.ts

@@ -0,0 +1,30 @@
+// The SUPPLY-only agentic cockpit (ADR 0056, H5 / #148) — the app-side core the Urban page + browser
+// shells boot. It renders the live worker/supply list (family, host, current jobs, liveness) from the
+// H1 registry snapshot and streams a drilled-in worker's terminal over the H3 relay, reusing the
+// packaged `@nanobpm/agentic/cockpit` relay client + resume-from-offset terminal session.
+//
+// The DEMAND×supply matrix, missing-agent-type reds, and diversity-SLO lights are OUT OF SCOPE for
+// this epic (#142) and deferred to the paired enrolment epic #152.
+export {
+  bootSupplyCockpit,
+  type CreateTerminal,
+  type SupplyCockpitEnv,
+  type SupplyCockpitHandle,
+  type TimerHandle,
+} from "./supply-boot.ts";
+export {
+  type RenderSupplyOptions,
+  renderSupply,
+  type SupplyDom,
+} from "./supply-render.ts";
+export {
+  type Liveness,
+  type SupplyLeafReport,
+  type SupplyLeafView,
+  type SupplyReport,
+  type SupplyView,
+  type SupplyViewOptions,
+  type SupplyWorkerReport,
+  type SupplyWorkerView,
+  supplyView,
+} from "./supply-view.ts";

package/app/agentic/cockpit/supply-boot.test.ts

@@ -0,0 +1,279 @@
+// Unit tests for the SUPPLY cockpit boot layer (H5 / #148), on the injected fake DOM + fake sockets.
+//
+// These are the acceptance's testable heart: the cockpit renders the live worker/supply list; drilling
+// a worker streams its terminal; the terminal survives a poll refresh AND a reconnect (resume-from-
+// offset, no loss/dup); the poll is self-scheduling. No real browser, no real socket, single run.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { FakeDocument, FakeElement, FakeSocket } from "../../../test/agentic-cockpit-doubles.ts";
+import { bootSupplyCockpit, type SupplyCockpitEnv } from "./supply-boot.ts";
+import type { SupplyReport } from "./supply-view.ts";
+
+const flush = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+const served: SupplyReport = {
+  count: 1,
+  workers: [{ instance: "wk-a", identity: "leaf-1", stream: "wk-a", family: "senior", host: "h1", jobKeys: [], live: true, staleMs: 0 }],
+  leaves: [
+    {
+      token: "leaf-1",
+      workers: [{ instance: "wk-a", identity: "leaf-1", stream: "wk-a", family: "senior", host: "h1", jobKeys: [], live: true, staleMs: 0 }],
+    },
+  ],
+};
+
+interface Rig {
+  readonly env: SupplyCockpitEnv;
+  readonly host: FakeElement;
+  readonly sockets: FakeSocket[];
+  readonly terminalWrites: string[];
+  terminalMounts: number;
+  terminalDisposes: number;
+  readonly timers: Array<{ run: () => void; ms: number }>;
+  reconnect: (() => void) | undefined;
+  report: SupplyReport;
+  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(),
+      fetchSupply: () => 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 worker/supply list into the host", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  assert.equal(r.host.byData("leaf", "leaf-1").length, 1);
+  assert.equal(r.host.byData("worker", "wk-a").length, 1);
+});
+
+test("a later poll reflects a changed report (a worker going down)", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  assert.equal(r.host.byData("worker", "wk-a")[0]?.getAttribute("data-liveness"), "live");
+
+  r.report = {
+    count: 1,
+    workers: [{ instance: "wk-a", identity: "leaf-1", stream: "wk-a", family: "senior", host: "h1", jobKeys: [], live: false, staleMs: 0 }],
+    leaves: [
+      {
+        token: "leaf-1",
+        workers: [{ instance: "wk-a", identity: "leaf-1", stream: "wk-a", family: "senior", host: "h1", jobKeys: [], live: false, staleMs: 0 }],
+      },
+    ],
+  };
+  await cockpit.refresh();
+  assert.equal(r.host.byData("worker", "wk-a")[0]?.getAttribute("data-liveness"), "down");
+});
+
+test("drilling into a worker subscribes its relay stream on connect", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("wk-a");
+  assert.equal(cockpit.currentStream, "wk-a");
+  assert.equal(r.sockets.length, 1);
+
+  r.sockets[0]?.fireOpen();
+  const subs = r.sockets[0]?.subscribeFrames() ?? [];
+  assert.equal(subs.length, 1);
+  assert.deepEqual(subs[0]?.payload, { op: "subscribe", stream: "wk-a", from: 0, credit: 1024 });
+});
+
+test("clicking a rendered worker button drills its stream", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  const button = r.host.byClass("cockpit-worker").find((b) => b.getAttribute("data-stream") === "wk-a");
+  button?.dispatch("click");
+  assert.equal(cockpit.currentStream, "wk-a");
+  assert.equal(r.sockets.length, 1);
+});
+
+test("relay output is written to the drilled worker's terminal", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("wk-a");
+  r.sockets[0]?.fireOpen();
+  r.sockets[0]?.deliver({ lane: "bulk", family: "relay", seq: 0, payload: { stream: "wk-a", offset: 0, chunk: "boot\n" } });
+  assert.deepEqual(r.terminalWrites, ["boot\n"]);
+});
+
+test("the terminal survives a list refresh — it is not re-mounted and keeps streaming", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("wk-a");
+  r.sockets[0]?.fireOpen();
+  r.sockets[0]?.deliver({ lane: "bulk", family: "relay", seq: 0, payload: { stream: "wk-a", offset: 0, chunk: "a" } });
+
+  await cockpit.refresh(); // a poll re-renders the worker list
+  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: "wk-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 = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("wk-a");
+
+  const s1 = r.sockets[0];
+  s1?.fireOpen();
+  s1?.deliver({ lane: "bulk", family: "relay", seq: 0, payload: { stream: "wk-a", offset: 0, chunk: "a" } });
+  s1?.deliver({ lane: "bulk", family: "relay", seq: 1, payload: { stream: "wk-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: "wk-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: "wk-a", offset: 1, chunk: "b" } });
+  s2?.deliver({ lane: "bulk", family: "relay", seq: 1, payload: { stream: "wk-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 + disposes the prior", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("wk-a");
+  cockpit.drill("wk-a");
+  assert.equal(r.sockets.length, 1);
+  assert.equal(r.terminalMounts, 1);
+  assert.equal(r.terminalDisposes, 0);
+
+  cockpit.drill("wk-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(r.terminalDisposes, 1, "prior terminal disposed on stream switch");
+  assert.equal(cockpit.currentStream, "wk-b");
+});
+
+test("start runs a pass and self-schedules the next; stop halts it", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  cockpit.start();
+  await flush();
+  assert.equal(r.host.byData("worker", "wk-a").length, 1, "first pass rendered");
+  assert.equal(r.timers.length, 1, "next pass scheduled once");
+
+  r.timers[0]?.run();
+  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 stop→start race does not leave two overlapping poll chains scheduling", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  cockpit.start();
+  cockpit.stop();
+  cockpit.start();
+  await flush();
+  assert.equal(r.timers.length, 1, "exactly one poll chain scheduled after the race");
+  cockpit.stop();
+});
+
+test("a fetch error is reported and does not wedge the poll", async () => {
+  const r = rig();
+  const failing: SupplyCockpitEnv = { ...r.env, fetchSupply: () => Promise.reject(new Error("boom")) };
+  const cockpit = bootSupplyCockpit(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 = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("wk-a");
+  cockpit.dispose();
+  assert.equal(r.sockets[0]?.closed, true);
+  assert.equal(r.terminalDisposes, 1);
+});
+
+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(
+      () => bootSupplyCockpit({ ...base, refreshMs }),
+      /refreshMs must be a positive safe integer/,
+      `refreshMs ${refreshMs} should be rejected`,
+    );
+  }
+});
+
+test("injecting setTimer without clearTimer (or vice versa) fails fast", () => {
+  const base = rig().env;
+  const noop = () => 0;
+  assert.throws(
+    () => bootSupplyCockpit({ ...base, setTimer: noop, clearTimer: undefined }),
+    /setTimer and clearTimer must be provided together/,
+  );
+  assert.throws(
+    () => bootSupplyCockpit({ ...base, setTimer: undefined, clearTimer: () => {} }),
+    /setTimer and clearTimer must be provided together/,
+  );
+});

package/app/agentic/cockpit/supply-boot.ts

@@ -0,0 +1,282 @@
+// The SUPPLY-only cockpit boot/orchestration layer (ADR 0056, H5 / #148).
+//
+// Wires the supply cockpit together from injected capabilities, with NO direct dependency on the
+// browser, a socket implementation, or xterm.js — everything is passed in ({@link SupplyCockpitEnv}).
+// That is what lets the same page render identically embedded (console App View, ADR 0057) and
+// standalone (the shells differ only in the `host` element and the concrete capabilities), and what
+// makes the live-refresh + drill-in + resume-on-reconnect path unit-testable on Node.
+//
+// It mirrors the packaged `@nanobpm/agentic/cockpit` boot DISCIPLINE (a self-scheduling poll; a
+// persistent terminal region a refresh never wipes; drill-in that resumes-from-offset on every
+// reconnect) but renders the SUPPLY-only worker list ({@link ./supply-render.ts}) instead of the
+// demand×supply matrix. The genuinely reusable, correctness-critical parts — the relay client and the
+// resume-from-offset terminal session — are REUSED from the package ({@link RelayChannelClient},
+// {@link TerminalSession}); only the supply projection the package does not provide is authored here.
+//
+// Responsibilities:
+//  - a self-scheduling poll of the app's SUPPLY report that re-renders the worker list each pass (a
+//    slow fetch can't overlap the next — mirrors the nano-workforce review-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 list refresh never wipes it),
+//    and re-attach on every reconnect so the terminal SURVIVES a cockpit reconnect via resume-from-offset.
+import {
+  type DocumentLike,
+  type ElementLike,
+  RelayChannelClient,
+  type Scheduler,
+  type SocketFactory,
+  TerminalSession,
+  type TerminalSink,
+} from "@nanobpm/agentic/cockpit";
+import { renderSupply } from "./supply-render.ts";
+import type { SupplyReport } from "./supply-view.ts";
+import { supplyView } from "./supply-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 SupplyCockpitEnv {
+  /** 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 SUPPLY report (e.g. over HTTP from the app's `/agentic/supply` endpoint). */
+  readonly fetchSupply: () => Promise<SupplyReport>;
+  /** 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 pair with {@link clearTimer}. */
+  readonly setTimer?: (run: () => void, ms: number) => TimerHandle;
+  /** Cancels a poll timer. Default `clearTimeout`. Must pair 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;
+  /** A live worker idle longer than this (ms) grades `stale`. Default 15000. */
+  readonly staleAfterMs?: number;
+  /** Notified of a fetch/render/relay error (the poll keeps going). */
+  readonly onError?: (err: unknown) => void;
+}
+
+/** The running supply cockpit; dispose to stop polling and tear down the terminal. */
+export interface SupplyCockpitHandle {
+  /** 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;
+
+function isPosInt(value: number): boolean {
+  return Number.isSafeInteger(value) && value > 0;
+}
+
+interface Drill {
+  readonly stream: string;
+  readonly client: RelayChannelClient;
+}
+
+class SupplyCockpit implements SupplyCockpitHandle {
+  readonly #env: SupplyCockpitEnv;
+  readonly #listRegion: 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.
+  #generation = 0;
+
+  constructor(env: SupplyCockpitEnv) {
+    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 endpoint. Require
+    // a positive safe integer up-front so a bad env option fails loudly instead.
+    if (!isPosInt(this.#refreshMs)) {
+      throw new RangeError(`SupplyCockpitEnv.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("SupplyCockpitEnv.setTimer and clearTimer must be provided together (or neither)");
+    }
+    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 list 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.#listRegion = env.doc.createElement("div");
+    this.#listRegion.className = "cockpit-supply-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.#listRegion);
+    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: SupplyReport;
+    try {
+      report = await this.#env.fetchSupply();
+    } catch (err) {
+      this.#env.onError?.(err);
+      return;
+    }
+    if (this.#disposed) return;
+    try {
+      renderSupply(this.#listRegion, this.#env.doc, supplyView(report, { staleAfterMs: this.#env.staleAfterMs }), {
+        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.
+    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
+    // (createTerminal, an invalid TerminalSession credit, or connect throwing) can't leave #drill
+    // pointing at an already-closed client. #drill is re-set only once the new client is fully wired.
+    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).
+    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 supply cockpit against an injected environment. Call {@link SupplyCockpitHandle.start} to poll. */
+export function bootSupplyCockpit(env: SupplyCockpitEnv): SupplyCockpitHandle {
+  return new SupplyCockpit(env);
+}