@nylorun/runtime 0.15.1-beta → 0.16.0-beta

package/dist/harness-api/start.js

@@ -0,0 +1,118 @@
+import { isWorkflowManifest } from "../core/flow-host.js";
+import { sandboxWorkspaceOf } from "../sandbox/share.js";
+import { ownedTx } from "../store/ownership.js";
+import { sandboxLookup } from "../tenant/context.js";
+import { checkParity, foldTranscriptWithCursor, leanState, transcriptOf, transcriptUpdates, withTranscript, } from "../tenant/history.js";
+import { usesFixtureModel } from "../tenant/model-setting.js";
+import { rebaseSessionState, sessionToolsOf, turnManifestOf } from "../tenant/session.js";
+import { bulkOutcomes } from "./record.js";
+/** How long a run waits in its lease for a pending Action's outcome (F6.2), by default. */
+const ACTION_HOLD_MS = 5 * 60_000;
+/** Segment rollover defaults (Model Calls §10), well inside the advance deadline. */
+const ROLLOVER_STEPS = 50;
+const ROLLOVER_MS = 20 * 60_000;
+/** The segment's starting transaction and fold. */
+export async function startSegment(ctx, lease, 
+/** For a harness: also the segment's outcomes and the sandbox's owner. */
+options = {}) {
+    const id = lease.sessionId;
+    const started = await ownedTx(ctx.store, id, lease.epoch, async (t, current) => {
+        if (!isWorkflowManifest(current.manifest) && current.checkpoint) {
+            rebaseSessionState(current, current.checkpoint.manifestHash);
+            await adoptStoredTranscript(t, current);
+            const cp = current.checkpoint;
+            current.checkpoint = { ...cp, state: current.state };
+            await t.put("sessions", id, current);
+        }
+        const fixtureModel = await usesFixtureModel(t);
+        if (!options.harness)
+            return { current, fixtureModel, outcomes: [], sandbox: { ownerId: id } };
+        const sandbox = sandboxWorkspaceOf(current, await sandboxLookup(t, current.id));
+        const resource = sandbox.sandboxId === undefined ? undefined : await t.sandboxResource(sandbox.sandboxId);
+        return {
+            current,
+            fixtureModel,
+            outcomes: current.checkpoint ? await bulkOutcomes(t, current, current.checkpoint) : [],
+            sandbox,
+            ...(resource?.pod ? { pod: { id: resource.id, pod: resource.pod } } : {}),
+        };
+    });
+    // One history (P0.3): the engine resumes from the transcript folded from the record.
+    const { current } = started;
+    const cp = current.checkpoint;
+    if (isWorkflowManifest(current.manifest) || !cp?.state)
+        return { ...started, transcript: [], cursor: -1 };
+    const { transcript, cursor } = await foldSession(ctx, current);
+    checkParity(id, transcript, transcriptOf(cp.state));
+    return { ...started, transcript, cursor };
+}
+/** The run's `turn.start`. */
+export function buildTurnStart(ctx, segment) {
+    const { current } = segment;
+    const flow = isWorkflowManifest(current.manifest);
+    const cp = current.checkpoint;
+    const input = cp.input;
+    return {
+        type: !flow && (input?.kind === "approve" || input?.kind === "respond") ? "approval.answer" : "turn.start",
+        engine: flow ? "flow" : "agent",
+        manifest: flow ? current.manifest : turnManifestOf(current),
+        checkpoint: !flow && cp.state
+            ? { ...cp, state: withTranscript(cp.state, []) }
+            : cp,
+        ...(flow ? {} : { sessionTools: sessionToolsOf(current.mcpSnapshot) ?? [] }),
+        outcomes: segment.outcomes,
+        transcript: { cursor: segment.cursor },
+        options: {
+            ...(flow
+                ? { flowLimits: ctx.flowLimits }
+                : { yieldAfter: yieldAfterOf(ctx) }),
+            fixtureModel: segment.fixtureModel,
+            holdMs: ctx.config.actionHoldMs ?? ACTION_HOLD_MS,
+        },
+        routing: {
+            rootManifest: current.manifest,
+            pluginRoots: current.pluginRoots ?? {},
+            ...(current.mcpSnapshot ? { mcpSnapshot: current.mcpSnapshot } : {}),
+            sandbox: segment.sandbox,
+        },
+    };
+}
+/** The engine's yield budget for a segment. */
+export function yieldAfterOf(ctx) {
+    return {
+        steps: ctx.config.rollover?.steps ?? ROLLOVER_STEPS,
+        ms: ctx.config.rollover?.ms ?? ROLLOVER_MS,
+    };
+}
+/**
+ * A session written before transcripts were recorded keeps its transcript on its row: record
+ * it once (the turn's starting transcript, then the turn so far), and store the row lean.
+ */
+async function adoptStoredTranscript(t, s) {
+    if (s.history)
+        return;
+    const now = transcriptOf(s.state);
+    const start = s.activeTurnId ? transcriptOf(s.turnStartState) : now;
+    if (now.length === 0 && start.length === 0)
+        return;
+    let first;
+    const write = async (turnId, updates) => {
+        for (const update of updates) {
+            const event = await t.event(s.id, turnId, "transcript.updated", update);
+            first ??= event.seq;
+        }
+    };
+    await write(null, transcriptUpdates([], start));
+    if (s.activeTurnId)
+        await write(s.activeTurnId, transcriptUpdates(start, now));
+    s.history = { from: first ?? 0, snapshot: first ?? 0 };
+    s.state = leanState(s.state);
+    s.turnStartState = leanState(s.turnStartState);
+}
+/** The session's transcript, folded from its record from `history.from`, and its cursor. */
+async function foldSession(ctx, s) {
+    const rows = await ctx.store
+        .record()
+        .readRange(ctx.store.tenantId, s.id, s.history?.from ?? 0, Number.MAX_SAFE_INTEGER);
+    return foldTranscriptWithCursor(rows.map((row) => row.body));
+}

package/dist/harness-api/workspace.d.ts

@@ -0,0 +1,53 @@
+import type { CapabilityManifest, SandboxToolName } from "@nylorun/core/define";
+import type { SandboxManager, SandboxSessionRef } from "../sandbox/manager.js";
+import type { SandboxSelectionReport } from "../sandbox/select.js";
+import type { SandboxToolOutcome } from "../sandbox/tools.js";
+import type { SessionStore } from "../store/types.js";
+import type { Logger } from "../tenant/types.js";
+import { type HarnessApiServer } from "./server.js";
+/** The sandbox selection, as `GET /v1/tenant/sandbox` and Tenant status report it. */
+export type WorkspaceReport = SandboxSelectionReport & {
+    readonly defaultImage: string;
+};
+type Exists = (id: string) => boolean | Promise<boolean>;
+export interface WorkspacePort {
+    /** Runs one sandbox tool in the workspace of `session`. */
+    run(session: SandboxSessionRef, capability: CapabilityManifest, toolName: SandboxToolName, input: unknown, signal: AbortSignal): Promise<SandboxToolOutcome>;
+    /** Lists the files under `dir` of the workspace of `session` (the turn-end export, F8.2). */
+    listFiles(session: SandboxSessionRef, capability: CapabilityManifest, dir: string, maxEntries: number, signal: AbortSignal): ReturnType<SandboxManager["listFiles"]>;
+    /** Reads a file of the workspace of `session` as bytes, at most `maxBytes` (`save_artifact`). */
+    readBytes(session: SandboxSessionRef, capability: CapabilityManifest, path: string, maxBytes: number, signal: AbortSignal): ReturnType<SandboxManager["readBytes"]>;
+    report(): Promise<WorkspaceReport>;
+    /** One Tenant sweep pass: stop idle workspaces, remove those whose owner is gone. */
+    sweep(options: {
+        now?: number;
+        sessionExists: Exists;
+        sandboxExists: Exists;
+    }): Promise<void>;
+    /** Deletes sandbox resource `sandboxId`'s workspace (the resource was deleted). */
+    removeSandbox(sandboxId: string): Promise<void>;
+    /** Deletes every workspace with its files (a sandboxes reset). */
+    removeAll(): Promise<void>;
+    close(): Promise<void>;
+}
+/** The Tenant's own SandboxManager. */
+export declare function localWorkspace(manager: SandboxManager): WorkspacePort;
+export interface RemoteWorkspaceOptions {
+    readonly server: HarnessApiServer;
+    readonly store: SessionStore;
+    readonly logger: Logger;
+    /** The sandbox backend preference, reported while no harness serves workspaces. */
+    readonly preference: string;
+    /** The pod sandbox whose host serves these workspaces (F7.2). */
+    readonly pod?: string;
+}
+/** The workspaces of the harness that serves them. */
+export declare function remoteWorkspace(options: RemoteWorkspaceOptions): WorkspacePort;
+/**
+ * Routes the workspaces of sessions attached to a pod sandbox to that sandbox's engine (F7.2);
+ * everything else goes to `base`. `podOf` says whether a sandbox resource is a pod sandbox.
+ */
+export declare function withPodWorkspaces(base: WorkspacePort, options: Omit<RemoteWorkspaceOptions, "pod"> & {
+    readonly isPod: (sandboxId: string) => Promise<boolean>;
+}): WorkspacePort;
+export {};

package/dist/harness-api/workspace.js

@@ -0,0 +1,201 @@
+/**
+ * The workspace capability (F6.2): what core does with the Tenant's sandbox workspaces outside a
+ * run. `ctx.sandbox` is a `WorkspacePort`: the sandbox tool routes (`POST
+ * /v1/sessions/:id/sandbox/:tool` and an Action endpoint's `POST /v1/actions/:id/sandbox/:tool`),
+ * Tenant status, the Tenant sweep, a sandbox resource's deletion and a sandboxes reset.
+ *
+ * - **In process** (`localWorkspace`): the Tenant's own SandboxManager, which its in-process
+ *   harness also runs sandbox tools with.
+ * - **Remote** (`remoteWorkspace`): the harness that declared `workspace` in its `hello` holds
+ *   the workspaces. `bash` becomes `workspace.exec`, `read`/`grep`/`glob` `workspace.read`,
+ *   `write`/`edit` `workspace.write`; a request is aborted when its HTTP client leaves. With no
+ *   such harness connected a tool call is `503 request_rejected`. The sweep asks the harness to
+ *   stop idle workspaces and list them (`workspace.sweep`), decides which owners are gone, and
+ *   removes theirs (`workspace.remove`); it also keeps the `sandboxes` table in step with the
+ *   list.
+ * - **Pod sandboxes** (F7.2, `withPodWorkspaces`): a session attached to a pod sandbox has its
+ *   workspace in the pod, served by the sandbox's engine (its host connection). Its tool calls,
+ *   listings and reads go there whatever serves the other workspaces; with the pod stopped or
+ *   starting they are `409 sandbox_unavailable`.
+ */
+import { HarnessApiError } from "@nylorun/core/harness-api";
+import { DEFAULT_SANDBOX_IMAGE } from "../sandbox/policy.js";
+import { fail } from "../tenant/http.js";
+import { NoWorkspaceHarness } from "./server.js";
+/** The Tenant's own SandboxManager. */
+export function localWorkspace(manager) {
+    return {
+        run: (session, capability, toolName, input, signal) => manager.run(session, capability, toolName, input, signal),
+        listFiles: (session, capability, dir, maxEntries, signal) => manager.listFiles(session, capability, dir, maxEntries, signal),
+        readBytes: (session, capability, path, maxBytes, signal) => manager.readBytes(session, capability, path, maxBytes, signal),
+        report: () => manager.report(),
+        sweep: (options) => manager.sweep(options),
+        removeSandbox: (sandboxId) => manager.removeSandbox(sandboxId),
+        removeAll: () => manager.reconcile(() => false, () => false),
+        close: () => manager.close(),
+    };
+}
+const METHODS = {
+    bash: "workspace.exec",
+    read: "workspace.read",
+    grep: "workspace.read",
+    glob: "workspace.read",
+    write: "workspace.write",
+    edit: "workspace.write",
+};
+function sessionOf(session) {
+    return {
+        ownerId: session.id,
+        ...(session.sandboxId === undefined ? {} : { sandboxId: session.sandboxId }),
+        activeTurnId: session.activeTurnId,
+    };
+}
+/** The workspaces of the harness that serves them. */
+export function remoteWorkspace(options) {
+    const { store } = options;
+    const target = options.pod === undefined ? undefined : { pod: options.pod };
+    const unavailable = (error) => error.pod === undefined
+        ? fail(503, error.message, { code: "request_rejected" })
+        : fail(409, error.message, { code: "sandbox_unavailable" });
+    /** The harness's answer, or `undefined` when none serves workspaces. */
+    const ask = async (method, params, signal) => {
+        try {
+            return await options.server.workspace(method, params, signal);
+        }
+        catch (error) {
+            if (error instanceof NoWorkspaceHarness)
+                return undefined;
+            throw error;
+        }
+    };
+    const sweep = async (sessionExists, sandboxExists, now) => {
+        const answer = await ask("workspace.sweep", now === undefined ? {} : { now });
+        if (!answer)
+            return;
+        const { workspaces } = answer;
+        const gone = [];
+        for (const record of workspaces) {
+            const kept = record.sandboxId === undefined
+                ? await sessionExists(record.sessionId)
+                : await sandboxExists(record.sandboxId);
+            if (!kept)
+                gone.push(record.key);
+        }
+        if (gone.length > 0)
+            await ask("workspace.remove", { keys: gone });
+        // The `sandboxes` table follows the harness: what it no longer runs is stopped, what it
+        // removed is gone.
+        const listed = new Map(workspaces.map((record) => [record.key, record]));
+        await store.tx(async (t) => {
+            for (const row of await t.listSandboxes()) {
+                const record = listed.get(row.key);
+                if (!record || gone.includes(row.key))
+                    await t.delete("sandboxes", row.key);
+                else if (record.state !== row.state)
+                    await t.put("sandboxes", row.key, { ...row, state: record.state });
+            }
+        });
+    };
+    return {
+        async run(session, capability, toolName, input, signal) {
+            try {
+                return (await options.server.workspace(METHODS[toolName], {
+                    session: sessionOf(session),
+                    spec: capability.sandbox ?? {},
+                    tool: toolName,
+                    input: input ?? {},
+                }, signal, target));
+            }
+            catch (error) {
+                if (error instanceof NoWorkspaceHarness)
+                    return unavailable(error);
+                if (error instanceof HarnessApiError && error.code === "unavailable" && !signal.aborted)
+                    return fail(503, `The harness serving workspaces went away: ${error.message}`, {
+                        code: "request_rejected",
+                    });
+                throw error;
+            }
+        },
+        async listFiles(session, capability, dir, maxEntries, signal) {
+            try {
+                const answer = (await options.server.workspace("workspace.read", { session: sessionOf(session), spec: capability.sandbox ?? {}, list: { dir, maxEntries } }, signal, target));
+                if (answer.kind === "listed")
+                    return {
+                        kind: "listed",
+                        path: String(answer.path),
+                        listing: answer.listing,
+                    };
+                if (answer.kind === "missing")
+                    return { kind: "missing", path: String(answer.path) };
+                return { kind: "failed", code: String(answer.code), message: String(answer.message) };
+            }
+            catch (error) {
+                // No harness holds the workspaces: there is nothing to export.
+                if (error instanceof NoWorkspaceHarness)
+                    return { kind: "missing", path: dir };
+                throw error;
+            }
+        },
+        async readBytes(session, capability, path, maxBytes, signal) {
+            try {
+                const answer = (await options.server.workspace("workspace.read", {
+                    session: sessionOf(session),
+                    spec: capability.sandbox ?? {},
+                    bytes: { path, maxBytes },
+                }, signal, target));
+                if (answer.kind === "read")
+                    return { kind: "read", path: String(answer.path), bytes: new Uint8Array(Buffer.from(String(answer.base64), "base64")) };
+                if (answer.kind === "missing")
+                    return { kind: "missing", path: String(answer.path) };
+                return { kind: "failed", code: String(answer.code), message: String(answer.message) };
+            }
+            catch (error) {
+                if (error instanceof NoWorkspaceHarness)
+                    return { kind: "failed", code: "sandbox.unavailable", message: error.message };
+                throw error;
+            }
+        },
+        async report() {
+            const answer = await ask("workspace.report", {}).catch(() => undefined);
+            if (answer)
+                return answer;
+            return {
+                preference: options.preference === "virtual" ? "virtual" : "auto",
+                backend: null,
+                isolation: null,
+                reason: "No harness serving workspaces is connected",
+                probes: [],
+                defaultImage: DEFAULT_SANDBOX_IMAGE,
+            };
+        },
+        sweep: (pass) => sweep(pass.sessionExists, pass.sandboxExists, pass.now),
+        async removeSandbox(sandboxId) {
+            // With no harness connected, the next sweep removes it: its resource is gone.
+            await ask("workspace.remove", { sandboxIds: [sandboxId] });
+            await store.tx(async (t) => {
+                for (const row of await t.listSandboxes())
+                    if (row.sandboxId === sandboxId)
+                        await t.delete("sandboxes", row.key);
+            });
+        },
+        async removeAll() {
+            await ask("workspace.remove", { all: true });
+        },
+        async close() { },
+    };
+}
+/**
+ * Routes the workspaces of sessions attached to a pod sandbox to that sandbox's engine (F7.2);
+ * everything else goes to `base`. `podOf` says whether a sandbox resource is a pod sandbox.
+ */
+export function withPodWorkspaces(base, options) {
+    const routed = async (session) => session.sandboxId !== undefined && (await options.isPod(session.sandboxId))
+        ? remoteWorkspace({ ...options, pod: session.sandboxId })
+        : base;
+    return {
+        ...base,
+        run: async (session, capability, toolName, input, signal) => (await routed(session)).run(session, capability, toolName, input, signal),
+        listFiles: async (session, capability, dir, maxEntries, signal) => (await routed(session)).listFiles(session, capability, dir, maxEntries, signal),
+        readBytes: async (session, capability, path, maxBytes, signal) => (await routed(session)).readBytes(session, capability, path, maxBytes, signal),
+    };
+}

package/dist/harness-api/ws-server.d.ts

@@ -0,0 +1,34 @@
+import { type Server } from "node:http";
+import { type HarnessChannel } from "@nylorun/core/harness-api";
+import { type WsPortOptions } from "../harness/ws-port.js";
+import { type HostAuthority } from "../sandbox/join.js";
+import type { HarnessPeer } from "./server.js";
+/** Where a pod's engine exchanges its join token, and renews its host token. */
+export declare const HOST_JOIN_PATH = "/nylorun/harness/v1/host/join";
+export declare const HOST_RENEW_PATH = "/nylorun/harness/v1/host/renew";
+/** Attaches a harness's channel to the open Tenant; returns a function that detaches it. */
+export type HarnessAttach = (channel: HarnessChannel, peer: HarnessPeer) => () => void;
+export interface HarnessListenerOptions {
+    readonly host: string;
+    readonly port: number;
+    /** Exact `Host` values accepted (lowercase `name:port`); the loopback forms of the bound port are added. */
+    readonly allowedHosts: readonly string[];
+    /** `NYLORUN_HARNESS_TOKEN`; absent, only sandbox pods' host tokens are accepted. */
+    readonly token?: string;
+    /** The open Tenant's `attachHarness`, or undefined while there is none. */
+    readonly attach: () => Promise<HarnessAttach | undefined>;
+    /** The open Tenant's host authority (sandbox pods, F7.2), or undefined without one. */
+    readonly hosts?: () => Promise<HostAuthority | undefined>;
+    readonly logger: {
+        info(message: string, fields?: Record<string, unknown>): void;
+        warn(message: string, fields?: Record<string, unknown>): void;
+    };
+    readonly liveness?: Omit<WsPortOptions, "ping">;
+}
+export interface HarnessListener {
+    /** `ws://host:port/nylorun/harness/v1`. */
+    readonly url: string;
+    readonly server: Server;
+    close(): Promise<void>;
+}
+export declare function startHarnessListener(options: HarnessListenerOptions): Promise<HarnessListener>;

package/dist/harness-api/ws-server.js

@@ -0,0 +1,227 @@
+/**
+ * The Harness API listener (F6.2): core's own port for harnesses (`NYLORUN_HARNESS_LISTEN_*`,
+ * default 4200), apart from the Tenant and Admin APIs. It accepts the harness credential
+ * (`NYLORUN_HARNESS_TOKEN`), and nothing else does; nothing else is served here.
+ *
+ * An upgrade is accepted only on `/nylorun/harness/v1`, with a `Host` in the allowlist (421),
+ * `Authorization: Bearer <token>` (compared in constant time; 401) and `Nylorun-Harness-Api: 1`
+ * (426), while the Tenant is open (503). Frames are at most 64 MiB and every one is validated
+ * (`createChannel({ validate: true })`). Core pings every 30 s and drops a harness silent for
+ * 90 s; the connection then counts as lost (`connection.lost`).
+ *
+ * Sandbox pods (F7.2, D42) reach this listener too, on the Docker host's published port, and hold
+ * no harness token. A pod's engine exchanges its join token for a host token with `POST
+ * /nylorun/harness/v1/host/join` (`{ sandboxId, podUid, joinToken }`), renews it with `POST
+ * .../host/renew` (`Authorization: Bearer <host token>`), and upgrades with the host token as
+ * its bearer: that connection hosts its sandbox alone (`HarnessPeer.host`). Both answer
+ * `{ hostToken, egressToken, sandboxId, epoch, expiresAt }`; every refusal is the same 401. The
+ * harness token is never accepted as a host token, nor a host token anywhere but here.
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { createChannel } from "@nylorun/core/harness-api";
+import { WebSocketServer } from "ws";
+import { HARNESS_API_HEADER, HARNESS_API_PATH, HARNESS_MAX_PAYLOAD, wsPort, } from "../harness/ws-port.js";
+import { tokenType } from "../tenant/jwt.js";
+import { HOST_TOKEN_TYP } from "../tenant/host-token.js";
+import { HostAuthError } from "../sandbox/join.js";
+/** Where a pod's engine exchanges its join token, and renews its host token. */
+export const HOST_JOIN_PATH = `${HARNESS_API_PATH}/host/join`;
+export const HOST_RENEW_PATH = `${HARNESS_API_PATH}/host/renew`;
+/** A join's body is small. */
+const MAX_JOIN_BODY = 8 * 1024;
+function refuse(socket, status, text, headers = {}) {
+    const lines = [
+        `HTTP/1.1 ${status} ${text}`,
+        "Connection: close",
+        "Content-Length: 0",
+        ...Object.entries(headers).map(([name, value]) => `${name}: ${value}`),
+    ];
+    socket.end(`${lines.join("\r\n")}\r\n\r\n`);
+}
+function bearerOf(header) {
+    return /^Bearer\s+(\S+)$/i.exec(header?.trim() ?? "")?.[1];
+}
+function bearerMatches(header, token) {
+    const presented = bearerOf(header);
+    if (presented === undefined || token === undefined)
+        return false;
+    const a = createHash("sha256").update(presented).digest();
+    const b = createHash("sha256").update(token).digest();
+    return timingSafeEqual(a, b);
+}
+export async function startHarnessListener(options) {
+    let closing = false;
+    // A log line must never throw out of a socket callback (a closed Tenant's log is gone).
+    const log = (level) => (message, fields) => {
+        if (closing)
+            return;
+        try {
+            options.logger[level](message, fields);
+        }
+        catch {
+            /* nowhere to log */
+        }
+    };
+    const logger = { info: log("info"), warn: log("warn") };
+    const wss = new WebSocketServer({ noServer: true, maxPayload: HARNESS_MAX_PAYLOAD });
+    let allowed = new Set(options.allowedHosts.map((host) => host.toLowerCase()));
+    const reply = (response, status, body, headers = {}) => {
+        const text = body === undefined ? "" : JSON.stringify(body);
+        response.writeHead(status, {
+            connection: "close",
+            "cache-control": "no-store",
+            ...(body === undefined ? {} : { "content-type": "application/json" }),
+            ...headers,
+        });
+        response.end(text);
+    };
+    const readBody = (request) => new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        request.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_JOIN_BODY) {
+                reject(new HostAuthError(400, "The body is too large"));
+                request.destroy();
+            }
+            else
+                chunks.push(chunk);
+        });
+        request.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        request.on("error", reject);
+    });
+    /** `host/join` and `host/renew` (F7.2); everything else here is the WebSocket upgrade. */
+    const serveHost = async (request, response, path) => {
+        if (request.method !== "POST")
+            return reply(response, 405, undefined, { allow: "POST" });
+        if (!allowed.has(String(request.headers.host ?? "").toLowerCase()))
+            return reply(response, 421);
+        const authority = await options.hosts?.().catch(() => undefined);
+        if (!authority || closing)
+            return reply(response, 503, { error: { code: "unavailable", message: "Try again" } });
+        try {
+            const answer = path === HOST_JOIN_PATH
+                ? await authority.join(parseJoin(await readBody(request)))
+                : await authority.renew(bearerOf(request.headers.authorization) ?? "");
+            return reply(response, 200, answer);
+        }
+        catch (error) {
+            if (error instanceof HostAuthError) {
+                if (error.reason)
+                    logger.warn("sandbox_host_refused", { path, reason: error.reason });
+                return reply(response, error.status, { error: { code: error.status === 401 ? "unauthorized" : "invalid", message: error.message } }, error.status === 401 ? { "www-authenticate": "Bearer" } : {});
+            }
+            logger.warn("sandbox_host_failed", { path, message: error instanceof Error ? error.message : String(error) });
+            return reply(response, 503, { error: { code: "unavailable", message: "Try again" } });
+        }
+    };
+    // Plain requests get nothing but the pods' join and renewal: the listener speaks the Harness API.
+    const server = createServer((request, response) => {
+        const path = new URL(request.url ?? "/", "http://harness.local").pathname;
+        if (closing)
+            return reply(response, 503);
+        if ((path === HOST_JOIN_PATH || path === HOST_RENEW_PATH) && options.hosts) {
+            void serveHost(request, response, path);
+            return;
+        }
+        response.writeHead(426, { connection: "close", upgrade: "websocket" });
+        response.end();
+    });
+    server.on("upgrade", (request, socket, head) => {
+        socket.on("error", () => undefined);
+        const path = new URL(request.url ?? "/", "http://harness.local").pathname;
+        if (closing)
+            return refuse(socket, 503, "Service Unavailable");
+        if (path !== HARNESS_API_PATH)
+            return refuse(socket, 404, "Not Found");
+        if (!allowed.has(String(request.headers.host ?? "").toLowerCase()))
+            return refuse(socket, 421, "Misdirected Request");
+        const bearer = bearerOf(request.headers.authorization);
+        // A pod's host token (F7.2): checked against its sandbox before the upgrade.
+        const hostToken = bearer !== undefined && options.hosts && tokenType(bearer) === HOST_TOKEN_TYP;
+        if (!hostToken && !bearerMatches(request.headers.authorization, options.token))
+            return refuse(socket, 401, "Unauthorized", { "WWW-Authenticate": "Bearer" });
+        if (request.headers[HARNESS_API_HEADER] !== "1")
+            return refuse(socket, 426, "Upgrade Required", { [HARNESS_API_HEADER]: "1" });
+        const host = hostToken
+            ? options.hosts().then(async (authority) => {
+                if (!authority)
+                    return undefined;
+                const claims = await authority.verify(bearer);
+                return { sandboxId: claims.sandboxId, epoch: claims.epoch };
+            })
+            : Promise.resolve(undefined);
+        void Promise.all([options.attach(), host]).then(([attach, hosted]) => {
+            if (!attach || closing || (hostToken && !hosted))
+                return refuse(socket, 503, "Service Unavailable");
+            wss.handleUpgrade(request, socket, head, (ws) => {
+                const peer = {
+                    name: hosted
+                        ? `sandbox ${hosted.sandboxId}@${request.socket.remoteAddress ?? "unknown"}`
+                        : `harness@${request.socket.remoteAddress ?? "unknown"}`,
+                    ...(hosted ? { host: hosted } : {}),
+                };
+                const channel = createChannel(wsPort(ws, { ...options.liveness, ping: true }), { validate: true });
+                const detach = attach(channel, peer);
+                channel.onClose((reason) => {
+                    detach();
+                    logger.info("harness_disconnected", { peer: peer.name, reason });
+                });
+                logger.info("harness_connected", { peer: peer.name });
+            });
+        }, (error) => {
+            if (error instanceof HostAuthError) {
+                if (error.reason)
+                    logger.warn("sandbox_host_refused", { path, reason: error.reason });
+                return refuse(socket, 401, "Unauthorized", { "WWW-Authenticate": "Bearer" });
+            }
+            return refuse(socket, 503, "Service Unavailable");
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, options.host, () => {
+            server.off("error", reject);
+            server.on("error", (error) => logger.warn("harness_listener_error", { message: error.message }));
+            resolve();
+        });
+    });
+    const port = server.address().port;
+    allowed = new Set([...allowed, `localhost:${port}`, `127.0.0.1:${port}`, `[::1]:${port}`]);
+    const host = options.host.includes(":") ? `[${options.host}]` : options.host;
+    return {
+        url: `ws://${host}:${port}${HARNESS_API_PATH}`,
+        server,
+        async close() {
+            closing = true;
+            for (const client of wss.clients)
+                client.close(1001, "core is stopping");
+            const closed = new Promise((resolve) => server.close(() => resolve()));
+            server.closeAllConnections();
+            setTimeout(() => {
+                for (const client of wss.clients)
+                    client.terminate();
+            }, 1_000).unref();
+            await closed;
+            wss.close();
+        },
+    };
+}
+/** A join's body, or a 400. */
+function parseJoin(text) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw new HostAuthError(400, "A join is JSON: { sandboxId, podUid, joinToken }");
+    }
+    const { sandboxId, podUid, joinToken, volumeId } = (body ?? {});
+    if (typeof sandboxId !== "string" ||
+        typeof podUid !== "string" ||
+        typeof joinToken !== "string" ||
+        (volumeId !== undefined && typeof volumeId !== "string"))
+        throw new HostAuthError(400, "A join is JSON: { sandboxId, podUid, joinToken, volumeId? }");
+    return { sandboxId, podUid, joinToken, ...(volumeId === undefined ? {} : { volumeId }) };
+}