@nanobpm/agentic 0.1.0

package/dist/cockpit/relay-client.js

@@ -0,0 +1,192 @@
+/**
+ * The browser-side relay channel client — S8.
+ *
+ * Ties one relay stream's {@link TerminalSession} to a live WebSocket-style
+ * connection: it encodes the session's outbound relay messages into S0 frames
+ * ({@link encodeFrame}) on the control lane, decodes inbound frames
+ * ({@link decodeFrame}) and routes `relay`-family payloads back to the session,
+ * and — critically for "survives a cockpit reconnect" — re-opens the socket when
+ * it drops and fires {@link RelayChannelClientOptions.onOpen} on **every**
+ * (re)connect, so the caller re-attaches the session and resumes from its last
+ * offset.
+ *
+ * It is transport- and timer-injected: the socket comes from a
+ * {@link SocketFactory} and reconnect scheduling from an injected
+ * {@link Scheduler}, so the whole reconnect→resume path is exercised
+ * deterministically in tests with a fake socket and a manual scheduler — no real
+ * timers, no real network (AGENTS.md: no flaky tests, no test retries).
+ */
+import { isNonNegInt, RELAY_FAMILY } from "../relay/index.js";
+import { decodeFrame, encodeFrame, MAX_SEQ } from "../protocol/index.js";
+const CONTROL_LANE = "control";
+function defaultSchedule(run) {
+    setTimeout(run, 0);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Narrow a decoded `relay`-family payload to the inbound sub-protocol without an
+ * unchecked cast (the repo bans `as`): a data chunk `{ stream, offset, chunk }`
+ * or a resume ack `{ op: "subscribed", stream, gap, nextOffset }`. Any payload
+ * carrying an `op` field is treated as an op-message and rejected unless it is a
+ * well-formed known op, so a malformed/unknown op can never fall through and be
+ * mistaken for a data chunk.
+ */
+function asRelayInbound(payload) {
+    if (!isRecord(payload))
+        return null;
+    if ("op" in payload) {
+        if (payload.op === "subscribed" &&
+            typeof payload.stream === "string" &&
+            typeof payload.gap === "boolean" &&
+            isNonNegInt(payload.nextOffset)) {
+            return { op: "subscribed", stream: payload.stream, gap: payload.gap, nextOffset: payload.nextOffset };
+        }
+        return null;
+    }
+    if (typeof payload.stream === "string" && isNonNegInt(payload.offset) && typeof payload.chunk === "string") {
+        const data = { stream: payload.stream, offset: payload.offset, chunk: payload.chunk };
+        return data;
+    }
+    return null;
+}
+/**
+ * Manages one relay socket with automatic resume-on-reconnect. Construct once
+ * per drill-in and pair with a {@link TerminalSession}: wire the session's
+ * `send` to {@link sendRelay}, feed {@link RelayChannelClientOptions.onRelay} to
+ * `session.handle`, and call `session.attach()` from `onOpen`.
+ */
+export class RelayChannelClient {
+    #connect;
+    #onRelay;
+    #onOpen;
+    #onClose;
+    #onError;
+    #schedule;
+    #autoReconnect;
+    #socket;
+    #seq = 0;
+    #closed = false;
+    constructor(options) {
+        this.#connect = options.connect;
+        this.#onRelay = options.onRelay;
+        this.#onOpen = options.onOpen;
+        this.#onClose = options.onClose;
+        this.#onError = options.onError;
+        this.#schedule = options.schedule ?? defaultSchedule;
+        this.#autoReconnect = options.autoReconnect ?? true;
+    }
+    /** True once {@link close} has been called (no further reconnects). */
+    get isClosed() {
+        return this.#closed;
+    }
+    /** Open the first socket and wire its lifecycle. Idempotent while connected. */
+    open() {
+        if (this.#closed || this.#socket !== undefined)
+            return;
+        // Guard the injected factory: connect() can throw synchronously (e.g. the
+        // browser adapter's WebSocket constructor on an invalid URL / CSP block).
+        // An unguarded throw here escapes open()/#reconnect() and kills the
+        // reconnect→resume loop with no error surfaced. Route it to onError and, if
+        // autoReconnect is enabled, schedule a retry so the loop survives a
+        // transient connect failure — the same way #handleClose recovers a drop.
+        let socket;
+        try {
+            socket = this.#connect();
+        }
+        catch (err) {
+            this.#onError?.(err);
+            if (!this.#closed && this.#autoReconnect)
+                this.#schedule(() => this.#reconnect());
+            return;
+        }
+        this.#socket = socket;
+        socket.onMessage((bytes) => this.#receive(bytes));
+        // Guard the consumer callback the same way #receive() does: a consumer
+        // onOpen handler can throw, and an unguarded throw escapes the socket open
+        // callback. Route it to onError so a bad handler can't wedge the client.
+        socket.onOpen(() => {
+            try {
+                this.#onOpen?.();
+            }
+            catch (err) {
+                this.#onError?.(err);
+            }
+        });
+        socket.onClose(() => this.#handleClose());
+    }
+    /** Encode and send one outbound relay message on the control lane. */
+    sendRelay(message) {
+        const socket = this.#socket;
+        if (socket === undefined)
+            return;
+        const frame = { lane: CONTROL_LANE, family: RELAY_FAMILY, seq: this.#nextSeq(), payload: message };
+        try {
+            socket.send(encodeFrame(frame));
+        }
+        catch (err) {
+            this.#onError?.(err);
+        }
+    }
+    /** Close for good — no reconnect will follow. */
+    close() {
+        this.#closed = true;
+        const socket = this.#socket;
+        this.#socket = undefined;
+        socket?.close();
+    }
+    #nextSeq() {
+        const seq = this.#seq;
+        this.#seq = this.#seq >= MAX_SEQ ? 0 : this.#seq + 1;
+        return seq;
+    }
+    #receive(bytes) {
+        let frame;
+        try {
+            frame = decodeFrame(bytes);
+        }
+        catch (err) {
+            this.#onError?.(err);
+            return;
+        }
+        if (frame.family !== RELAY_FAMILY)
+            return;
+        const message = asRelayInbound(frame.payload);
+        if (message === null) {
+            this.#onError?.(new Error("malformed relay payload"));
+            return;
+        }
+        // Guard the consumer the same way decode/malformed errors are guarded: a
+        // handler (e.g. TerminalSession.handle) can throw on an unsafe offset via
+        // addSafeInt, and an unguarded throw here escapes the socket message
+        // callback and can wedge the relay client / page. Route it to onError.
+        try {
+            this.#onRelay(message);
+        }
+        catch (err) {
+            this.#onError?.(err);
+        }
+    }
+    #handleClose() {
+        this.#socket = undefined;
+        // Guard the consumer onClose: if it throws, an unguarded exception here
+        // skips the reconnect scheduling below and breaks the "survives reconnect"
+        // invariant for reasons unrelated to transport. Route it to onError, then
+        // continue with reconnect regardless.
+        try {
+            this.#onClose?.();
+        }
+        catch (err) {
+            this.#onError?.(err);
+        }
+        if (this.#closed || !this.#autoReconnect)
+            return;
+        this.#schedule(() => this.#reconnect());
+    }
+    #reconnect() {
+        if (this.#closed || this.#socket !== undefined)
+            return;
+        this.open();
+    }
+}

package/dist/cockpit/render.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The cockpit DOM renderer — S8.
+ *
+ * Renders a {@link CockpitView} into a host element: the demand×supply networks
+ * matrix, a red light per *missing agent type*, and the diversity-SLO light.
+ * Clicking a worker instance calls {@link RenderOptions.onDrill} with that
+ * instance's relay stream id. This renders only the *volatile* part of the page
+ * (the part that refreshes each poll); the drill-in terminal is owned by
+ * {@link mountCockpit} in a persistent region so it survives a matrix refresh.
+ *
+ * It renders against a **structural** DOM subset ({@link ElementLike} /
+ * {@link DocumentLike}) rather than the global `document`, for two reasons that
+ * matter to this slice:
+ *  1. it is the *same* function the standalone shell and the embedded (App View)
+ *     host both call — via the plain-JS `page/mount.js` adapter, which passes the
+ *     browser's real `document` and their own host element — so the two render
+ *     **identically** by construction (one code path, no standalone/embedded
+ *     branch); and
+ *  2. a plain in-memory fake satisfies the structural type, so the renderer is
+ *     unit-tested on Node with no DOM library and no `as` cast.
+ *
+ * These interfaces are a deliberately *minimal* subset, NOT lib.dom's `Element`/
+ * `Document`: the real DOM satisfies them at runtime (as `page/mount.js` — plain
+ * JS, untyped — relies on), but a real `HTMLElement` is not TS-assignable to
+ * {@link ElementLike} (lib.dom's `appendChild` is `Node`-constrained). Keeping the
+ * subset this narrow — rather than widening to lib.dom, which the in-memory fake
+ * could not satisfy without a banned `as` cast — is the tradeoff that buys the
+ * DOM-free Node tests. A TypeScript browser caller wanting to invoke
+ * {@link bootCockpit} directly supplies a thin structural adapter over the real DOM.
+ */
+import type { CockpitView } from "./view.ts";
+/** The minimal element surface the renderer builds against (the in-memory fake, and the real DOM at runtime, satisfy it — see file header). */
+export interface ElementLike {
+    className: string;
+    textContent: string | null;
+    setAttribute(name: string, value: string): void;
+    appendChild(child: ElementLike): ElementLike;
+    replaceChildren(): void;
+    addEventListener(type: string, handler: () => void): void;
+}
+/** The minimal document surface the renderer builds against (the in-memory fake, and the real DOM at runtime, satisfy it — see file header). */
+export interface DocumentLike {
+    createElement(tagName: string): ElementLike;
+}
+export interface RenderOptions {
+    /** Called with a worker instance's relay stream id when the operator drills in. */
+    readonly onDrill?: (stream: string) => void;
+}
+/** Handles into the rendered tree the caller may need. */
+export interface CockpitDom {
+    /** The freshly built root the view was rendered into. */
+    readonly root: ElementLike;
+}
+/**
+ * Render `view` into `host`, replacing whatever was there. Idempotent: call it
+ * again on every refresh to reflect the latest demand×supply snapshot.
+ */
+export declare function renderCockpit(host: ElementLike, doc: DocumentLike, view: CockpitView, options?: RenderOptions): CockpitDom;

package/dist/cockpit/render.js

@@ -0,0 +1,122 @@
+function el(doc, tag, className, text) {
+    const node = doc.createElement(tag);
+    if (className !== undefined)
+        node.className = className;
+    if (text !== undefined)
+        node.textContent = text;
+    return node;
+}
+function lightNode(doc, light) {
+    const row = el(doc, "div", "cockpit-light");
+    row.setAttribute("data-status", light.status);
+    row.setAttribute("data-light-id", light.id);
+    const dot = el(doc, "span", "cockpit-dot");
+    dot.setAttribute("data-status", light.status);
+    row.appendChild(dot);
+    row.appendChild(el(doc, "span", "cockpit-light-label", light.label));
+    if (light.detail !== undefined) {
+        const detail = el(doc, "span", "cockpit-light-detail", light.detail);
+        detail.setAttribute("title", light.detail);
+        row.appendChild(detail);
+    }
+    return row;
+}
+function statusBadge(doc, id, label, status) {
+    const badge = el(doc, "div", "cockpit-status", `${label}: ${status}`);
+    badge.setAttribute("data-status", status);
+    badge.setAttribute("data-badge-id", id);
+    return badge;
+}
+function tokenCell(doc, network, options) {
+    const table = el(doc, "table", "cockpit-tokens");
+    const thead = el(doc, "thead", "cockpit-tokens-thead");
+    const head = el(doc, "tr", "cockpit-tokens-head");
+    head.appendChild(el(doc, "th", "cockpit-th", "token"));
+    head.appendChild(el(doc, "th", "cockpit-th", "supply"));
+    head.appendChild(el(doc, "th", "cockpit-th", "workers"));
+    thead.appendChild(head);
+    table.appendChild(thead);
+    const tbody = el(doc, "tbody", "cockpit-tokens-tbody");
+    for (const token of network.tokens) {
+        const row = el(doc, "tr", "cockpit-token");
+        row.setAttribute("data-status", token.status);
+        row.setAttribute("data-token", token.token);
+        const dot = el(doc, "td", "cockpit-td");
+        const light = el(doc, "span", "cockpit-dot");
+        light.setAttribute("data-status", token.status);
+        dot.appendChild(light);
+        dot.appendChild(el(doc, "span", "cockpit-token-name", token.token));
+        row.appendChild(dot);
+        row.appendChild(el(doc, "td", "cockpit-td", String(token.supply)));
+        const workers = el(doc, "td", "cockpit-td cockpit-workers");
+        for (const instance of token.instances) {
+            const chip = el(doc, "button", "cockpit-worker", instance);
+            chip.setAttribute("data-stream", instance);
+            chip.setAttribute("type", "button");
+            const onDrill = options.onDrill;
+            if (onDrill !== undefined) {
+                chip.addEventListener("click", () => onDrill(instance));
+            }
+            workers.appendChild(chip);
+        }
+        row.appendChild(workers);
+        tbody.appendChild(row);
+    }
+    table.appendChild(tbody);
+    return table;
+}
+function networkSection(doc, network, options) {
+    const section = el(doc, "section", "cockpit-network");
+    section.setAttribute("data-status", network.status);
+    section.setAttribute("data-network", network.network);
+    const header = el(doc, "div", "cockpit-network-head");
+    const dot = el(doc, "span", "cockpit-dot");
+    dot.setAttribute("data-status", network.status);
+    header.appendChild(dot);
+    header.appendChild(el(doc, "span", "cockpit-network-name", network.network));
+    if (network.missing.length > 0) {
+        header.appendChild(el(doc, "span", "cockpit-network-missing", `missing: ${network.missing.join(", ")}`));
+    }
+    section.appendChild(header);
+    section.appendChild(tokenCell(doc, network, options));
+    return section;
+}
+function missingPanel(doc, view) {
+    const panel = el(doc, "aside", "cockpit-missing");
+    panel.setAttribute("data-empty", view.missingLights.length === 0 ? "true" : "false");
+    panel.appendChild(el(doc, "h2", "cockpit-panel-title", "Missing agent types"));
+    if (view.missingLights.length === 0) {
+        panel.appendChild(el(doc, "div", "cockpit-missing-none", "none — every demanded token is served"));
+        return panel;
+    }
+    for (const light of view.missingLights) {
+        panel.appendChild(lightNode(doc, light));
+    }
+    return panel;
+}
+/**
+ * Render `view` into `host`, replacing whatever was there. Idempotent: call it
+ * again on every refresh to reflect the latest demand×supply snapshot.
+ */
+export function renderCockpit(host, doc, view, options = {}) {
+    host.replaceChildren();
+    const root = el(doc, "div", "cockpit");
+    root.setAttribute("data-status", view.status);
+    const header = el(doc, "header", "cockpit-header");
+    header.appendChild(el(doc, "h1", "cockpit-title", "Agent networks — the cockpit"));
+    header.appendChild(statusBadge(doc, "overall", "overall", view.status));
+    header.appendChild(lightNode(doc, view.diversityLight));
+    root.appendChild(header);
+    root.appendChild(missingPanel(doc, view));
+    const matrix = el(doc, "div", "cockpit-matrix");
+    for (const network of view.networks) {
+        matrix.appendChild(networkSection(doc, network, options));
+    }
+    root.appendChild(matrix);
+    if (view.nonAgentic.length > 0) {
+        const footer = el(doc, "footer", "cockpit-nonagentic", `non-agentic task types: ${view.nonAgentic.join(", ")}`);
+        root.appendChild(footer);
+    }
+    host.appendChild(root);
+    return { root };
+}

package/dist/cockpit/terminal-session.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The worker terminal session — S8's drill-into-a-worker live terminal.
+ *
+ * A consumer of the S5 relay sub-protocol that **survives a cockpit reconnect**
+ * via resume-from-offset. It is deliberately timer-free and transport-free: it
+ * emits the relay messages to send ({@link RelaySend}) and consumes the relay
+ * messages received ({@link TerminalSession.handle}), tracking exactly one piece
+ * of durable state — `nextOffset`, the offset to resume from. On any (re)attach
+ * it re-subscribes from `nextOffset`, and it drops any replayed chunk it has
+ * already applied, so a reconnect neither loses nor double-writes output (within
+ * the relay ring's retained window). If the hub's `subscribed` ack reports a
+ * `nextOffset` (stream head) *below* our resume point — a hub restart/reset left
+ * us ahead of the stream — it clamps `nextOffset` back down so fresh chunks are
+ * not dropped as stale.
+ *
+ * The S5 relay wire (see `@nanobpm/agentic-relay`):
+ *  - outbound `{ op: "subscribe", stream, from, credit }` — (re)attach and resume,
+ *  - outbound `{ op: "credit", credit }`                  — grant more bulk credit,
+ *  - inbound  `{ op: "subscribed", stream, gap, nextOffset }` — the resume ack
+ *             (`gap: boolean` — the S5 wire flags whether chunks aged out),
+ *  - inbound  {@link RelayPayload} `{ stream, offset, chunk }` — a data chunk.
+ */
+import type { RelayPayload } from "../protocol/index.ts";
+/** The terminal sink the session writes decoded output to (xterm.js satisfies this). */
+export interface TerminalSink {
+    /** Append a chunk of terminal output. */
+    write(chunk: string): void;
+    /** Tear down the underlying terminal widget and its listeners, if any. */
+    dispose?(): void;
+}
+/** An outbound relay message the session asks its transport to send. */
+export type RelayOutbound = {
+    readonly op: "subscribe";
+    readonly stream: string;
+    readonly from: number;
+    readonly credit: number;
+} | {
+    readonly op: "credit";
+    readonly credit: number;
+};
+/** An inbound relay message the session consumes (a data chunk or a resume ack). */
+export type RelayInbound = RelayPayload | {
+    readonly op: "subscribed";
+    readonly stream: string;
+    readonly gap: boolean;
+    readonly nextOffset: number;
+};
+/** Sends one outbound relay message over the channel. */
+export type RelaySend = (message: RelayOutbound) => void;
+export interface TerminalSessionOptions {
+    /** The relay stream id (one worker's terminal). */
+    readonly stream: string;
+    /** Where decoded output is written. */
+    readonly sink: TerminalSink;
+    /** Emits outbound relay messages. */
+    readonly send: RelaySend;
+    /** Bulk credit requested on each (re)subscribe. Default 1024. */
+    readonly credit?: number;
+    /** Offset to resume from on first attach. Default 0 (from the start). */
+    readonly from?: number;
+    /** Notified when the resume ack reports a gap (chunks aged out of the ring). */
+    readonly onGap?: () => void;
+}
+/**
+ * A resume-from-offset consumer of one relay stream. Construct once per worker
+ * drill-in; call {@link attach} on every (re)connection and feed every inbound
+ * relay message to {@link handle}.
+ */
+export declare class TerminalSession {
+    #private;
+    constructor(options: TerminalSessionOptions);
+    /** The stream id this session follows. */
+    get stream(): string;
+    /** The offset the session will resume from on the next {@link attach}. */
+    get nextOffset(): number;
+    /** Whether the most recent resume ack reported a gap (false when none was lost). */
+    get gap(): boolean;
+    /**
+     * (Re)subscribe to the stream, resuming from {@link nextOffset}. Call this on
+     * first connect AND after every reconnect — because it always resumes from the
+     * offset just past the last applied chunk, a reconnect replays only the
+     * un-applied tail (no loss) and re-delivered chunks below `nextOffset` are
+     * dropped by {@link handle} (no duplication).
+     */
+    attach(): void;
+    /** Grant additional bulk credit (backpressure release) mid-stream. */
+    grant(credit: number): void;
+    /**
+     * Process one inbound relay message. A data chunk at or beyond `nextOffset` is
+     * written and advances the resume point; a chunk below it (a duplicate replay
+     * after a reconnect) is dropped. A resume ack records any gap and clamps the
+     * resume point down to the hub's head when we are ahead of it.
+     */
+    handle(message: RelayInbound): void;
+}

package/dist/cockpit/terminal-session.js

@@ -0,0 +1,123 @@
+import { addSafeInt, isNonNegInt, isPosInt } from "../relay/index.js";
+const DEFAULT_CREDIT = 1024;
+function isRelayData(message) {
+    return !("op" in message);
+}
+/**
+ * A resume-from-offset consumer of one relay stream. Construct once per worker
+ * drill-in; call {@link attach} on every (re)connection and feed every inbound
+ * relay message to {@link handle}.
+ */
+export class TerminalSession {
+    #stream;
+    #sink;
+    #send;
+    #credit;
+    #onGap;
+    /** The next offset we still need — everything below it has been applied. */
+    #nextOffset;
+    /** Whether the most recent resume ack reported a gap (retained window overrun). */
+    #gap = false;
+    constructor(options) {
+        this.#stream = options.stream;
+        this.#sink = options.sink;
+        this.#send = options.send;
+        this.#credit = options.credit ?? DEFAULT_CREDIT;
+        if (!isPosInt(this.#credit)) {
+            throw new RangeError(`TerminalSession.credit must be a positive safe integer, got ${this.#credit}`);
+        }
+        this.#onGap = options.onGap;
+        const from = options.from ?? 0;
+        if (!isNonNegInt(from)) {
+            throw new RangeError(`TerminalSession.from must be a non-negative safe integer, got ${from}`);
+        }
+        this.#nextOffset = from;
+    }
+    /** The stream id this session follows. */
+    get stream() {
+        return this.#stream;
+    }
+    /** The offset the session will resume from on the next {@link attach}. */
+    get nextOffset() {
+        return this.#nextOffset;
+    }
+    /** Whether the most recent resume ack reported a gap (false when none was lost). */
+    get gap() {
+        return this.#gap;
+    }
+    /**
+     * (Re)subscribe to the stream, resuming from {@link nextOffset}. Call this on
+     * first connect AND after every reconnect — because it always resumes from the
+     * offset just past the last applied chunk, a reconnect replays only the
+     * un-applied tail (no loss) and re-delivered chunks below `nextOffset` are
+     * dropped by {@link handle} (no duplication).
+     */
+    attach() {
+        this.#send({ op: "subscribe", stream: this.#stream, from: this.#nextOffset, credit: this.#credit });
+    }
+    /** Grant additional bulk credit (backpressure release) mid-stream. */
+    grant(credit) {
+        if (!isPosInt(credit)) {
+            throw new RangeError(`TerminalSession.grant credit must be a positive safe integer, got ${credit}`);
+        }
+        this.#send({ op: "credit", credit });
+    }
+    /**
+     * Process one inbound relay message. A data chunk at or beyond `nextOffset` is
+     * written and advances the resume point; a chunk below it (a duplicate replay
+     * after a reconnect) is dropped. A resume ack records any gap and clamps the
+     * resume point down to the hub's head when we are ahead of it.
+     */
+    handle(message) {
+        if (isRelayData(message)) {
+            this.#onData(message);
+            return;
+        }
+        if (message.op === "subscribed" && message.stream === this.#stream) {
+            this.#onSubscribed(message.gap, message.nextOffset);
+        }
+    }
+    #onData(data) {
+        if (data.stream !== this.#stream)
+            return;
+        // Idempotent apply: a reconnect resubscribes from nextOffset, so the hub may
+        // re-deliver the boundary chunk; anything we have already applied is dropped.
+        if (data.offset < this.#nextOffset)
+            return;
+        // Compute the next resume point BEFORE writing so the apply is atomic: a
+        // chunk at Number.MAX_SAFE_INTEGER makes addSafeInt throw, and it must throw
+        // before we touch the sink — otherwise the chunk is written but #nextOffset
+        // is not advanced, leaving a partially-applied state that re-delivers (and
+        // so duplicates) the chunk on reconnect. Advancing via addSafeInt also fails
+        // fast rather than overflowing into an unsafe nextOffset — that value would
+        // later be echoed in subscribe.from and lose precision on any JSON
+        // round-trip, silently corrupting resume semantics.
+        const nextOffset = addSafeInt(data.offset, 1, "nextOffset");
+        this.#sink.write(data.chunk);
+        this.#nextOffset = nextOffset;
+    }
+    #onSubscribed(gap, nextOffset) {
+        // Validate the ack's resume point exactly as the constructor validates
+        // `from`: `nextOffset` is echoed back into subscribe.from on the next
+        // attach, so a negative/NaN/unsafe value (from a buggy or malicious
+        // transport that bypasses RelayChannelClient's validation) would corrupt
+        // resume semantics or lose precision on a JSON round-trip. Fail fast.
+        if (!isNonNegInt(nextOffset)) {
+            throw new RangeError(`TerminalSession.subscribed nextOffset must be a non-negative safe integer, got ${nextOffset}`);
+        }
+        // Clamp our resume point down to the hub's current head when we are ahead of
+        // it. Without this, a hub restart/reset (or a `from` seeded past the head)
+        // leaves #nextOffset above every offset the hub will now emit, so #onData
+        // silently drops all fresh chunks until the stream catches back up — losing
+        // terminal output, possibly indefinitely. Only clamp DOWN: a head at or above
+        // #nextOffset is the normal case and must not skip un-applied chunks.
+        if (nextOffset < this.#nextOffset) {
+            this.#nextOffset = nextOffset;
+        }
+        // Record the gap on every ack so a later no-gap resume clears a prior gap.
+        this.#gap = gap;
+        if (gap) {
+            this.#onGap?.();
+        }
+    }
+}

package/dist/cockpit/view.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The cockpit view-model — S8.
+ *
+ * A pure, deterministic projection of the S4 {@link DemandSupplyReport} onto the
+ * shape the cockpit renders: a per-network demand×supply matrix, a red light per
+ * *missing agent type*, and the diversity-SLO state (from S3, carried through S4).
+ *
+ * It is deliberately framework-free and side-effect-free: the same report always
+ * yields the same {@link CockpitView}, so it is safe to diff frame-to-frame, to
+ * snapshot in a test, and to render identically whether the page is embedded in
+ * the console (App View) or served standalone — the view is the single source of
+ * truth both render paths consume.
+ */
+import type { DemandSupplyReport, SloStatus } from "../demand/index.ts";
+import type { DiversityReport } from "../vocab/index.ts";
+export type { SloStatus } from "../demand/index.ts";
+/** A three-state status light rendered as a coloured dot + label. */
+export interface CockpitLight {
+    /** Stable id for the DOM node / keyed diff. */
+    readonly id: string;
+    /** Human label shown next to the dot. */
+    readonly label: string;
+    /** The grade the dot colours to. */
+    readonly status: SloStatus;
+    /** Optional one-line detail (tooltip / secondary text). */
+    readonly detail?: string;
+}
+/** One demanded routing token as a matrix cell. */
+export interface CockpitTokenRow {
+    /** The demanded routing token. */
+    readonly token: string;
+    /** How many registered workers currently serve it. */
+    readonly supply: number;
+    /** The serving worker instances (provenance for the drill-in), sorted. */
+    readonly instances: readonly string[];
+    /** False when no worker serves it — a missing agent type. */
+    readonly satisfied: boolean;
+    /** GREEN when served, RED when missing. */
+    readonly status: SloStatus;
+}
+/** One network prefix as a matrix row. */
+export interface CockpitNetworkRow {
+    /** The network prefix bucket. */
+    readonly network: string;
+    /** Every demanded token in the bucket, sorted by token. */
+    readonly tokens: readonly CockpitTokenRow[];
+    /** The demanded tokens in this bucket with zero supply, sorted. */
+    readonly missing: readonly string[];
+    /** RED when the row has any missing agent type, else GREEN. */
+    readonly status: SloStatus;
+}
+/** The full renderable cockpit view. */
+export interface CockpitView {
+    /** The overall SLO state: worst of missing-agent and diversity. */
+    readonly status: SloStatus;
+    /** The demand×supply matrix, one row per network, sorted by network. */
+    readonly networks: readonly CockpitNetworkRow[];
+    /** Every missing agent type across all networks, sorted and de-duplicated. */
+    readonly missing: readonly string[];
+    /** One RED light per missing agent type (empty when nothing is missing). */
+    readonly missingLights: readonly CockpitLight[];
+    /** The S3 diversity report, carried through unchanged for detail rendering. */
+    readonly diversity: DiversityReport;
+    /** A single light summarising the diversity SLO. */
+    readonly diversityLight: CockpitLight;
+    /**
+     * Deployed task types that are not valid routing tokens (ordinary,
+     * non-agentic C8 jobs) — surfaced so an operator can spot a mistyped token,
+     * excluded from the agentic accounting.
+     */
+    readonly nonAgentic: readonly string[];
+}
+/**
+ * Derive the renderable cockpit view from an S4 demand×supply report.
+ *
+ * Pure and total: every list is already sorted by S4, so the derived view is
+ * stable and diff-friendly; no input mutates and no I/O happens.
+ */
+export declare function cockpitView(report: DemandSupplyReport): CockpitView;