@byok-sdk/server 0.1.0

package/dist/index.js

@@ -0,0 +1,2675 @@
+import { randomBytes, randomUUID, timingSafeEqual, createHmac, createHash, createPublicKey, verify } from 'crypto';
+import { jwtVerify, SignJWT } from 'jose';
+import { mkdir, writeFile, readFile } from 'fs/promises';
+import { mkdtempSync, mkdirSync, existsSync, chmodSync } from 'fs';
+import { tmpdir } from 'os';
+import path, { dirname } from 'path';
+import { Hono } from 'hono';
+import { CAPABILITY_FLAGS, canTransition, PROTOCOL_VERSION, encodeEnvelope, DAEMON_TO_SERVER_TYPES, createEnvelope, TASK_STATES, PairRequestSchema, ChallengeRequestSchema, TokenRequestSchema, CreateBlobRequestSchema, MessagesSendRequestSchema, decodeEnvelope } from '@byok-sdk/protocol';
+import { WebSocketServer } from 'ws';
+import { createRequire } from 'module';
+
+// src/auth.ts
+var ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
+var NONCE_TTL_MS = 5 * 60 * 1e3;
+var NONCE_SIGNING_DOMAIN = "byok-nonce-v1\n";
+function createHmacTokenSigner(secret = randomBytes(32)) {
+  return {
+    async sign(claims, expiresInSeconds) {
+      return new SignJWT({ deviceId: claims.deviceId, tenantId: claims.tenantId, productId: claims.productId }).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setExpirationTime(Math.floor(Date.now() / 1e3) + expiresInSeconds).sign(secret);
+    },
+    async verify(token) {
+      try {
+        const { payload } = await jwtVerify(token, secret);
+        if (typeof payload.deviceId !== "string") return void 0;
+        if (typeof payload.tenantId !== "string") return void 0;
+        if (typeof payload.productId !== "string") return void 0;
+        return { deviceId: payload.deviceId, tenantId: payload.tenantId, productId: payload.productId };
+      } catch {
+        return void 0;
+      }
+    }
+  };
+}
+async function mintAccessToken(signer, claims) {
+  const accessToken = await signer.sign(claims, ACCESS_TOKEN_TTL_SECONDS);
+  const expiresAt = new Date(Date.now() + ACCESS_TOKEN_TTL_SECONDS * 1e3).toISOString();
+  return { accessToken, expiresAt };
+}
+var DeviceRegistry = class _DeviceRegistry {
+  /** Keyed by {@link DeviceRegistry.key} — `(tenantId, deviceId)`. */
+  devices = /* @__PURE__ */ new Map();
+  /**
+   * Secondary index over the SAME record objects, for the two pre-tenant
+   * endpoints only (see {@link resolveByDeviceId}). Holding the same object
+   * reference means a revocation applied through the composite key is
+   * immediately visible here too — there is no second copy to keep in sync.
+   */
+  byDeviceId = /* @__PURE__ */ new Map();
+  static key(tenantId, deviceId) {
+    return `${tenantId}\0${deviceId}`;
+  }
+  /**
+   * Write a device row. Every identity field is required by
+   * {@link DeviceRegistration}, so a row with no tenant cannot be constructed
+   * — which is the whole point of S1.
+   */
+  register(device) {
+    const record = { ...device, revoked: false };
+    this.devices.set(_DeviceRegistry.key(record.tenantId, record.deviceId), record);
+    this.byDeviceId.set(record.deviceId, record);
+  }
+  /** The row `tenantId` owns under `deviceId`, or `undefined` — including when the device exists under a DIFFERENT tenant. */
+  get(tenantId, deviceId) {
+    return this.devices.get(_DeviceRegistry.key(tenantId, deviceId));
+  }
+  /**
+   * Revoke a device (public API via `createByokServer(...).devices.revoke`).
+   * Its next `/byok/challenge`, `/byok/token`, WSS connect, or authed HTTP
+   * call gets a 401; the daemon's only recourse is to re-run `/byok/pair`
+   * (docs/protocol.md §6.3). A tenant can only revoke its own devices: a
+   * (tenantId, deviceId) pair it does not own resolves to nothing and this is
+   * a no-op.
+   */
+  revoke(tenantId, deviceId) {
+    const record = this.get(tenantId, deviceId);
+    if (record) record.revoked = true;
+  }
+  /** Every known device row, across tenants — the in-process read model behind `ByokServer.machines.list()`. */
+  list() {
+    return [...this.devices.values()];
+  }
+  /**
+   * Resolve a device by its globally-unique id alone, WITHOUT a tenant in
+   * scope. Exists for exactly two callers — `POST /byok/challenge` and
+   * `POST /byok/token` — because those two carry no tenant at all: their
+   * request DTOs are the pinned wire contract (docs/protocol.md §6.2), the
+   * device authenticates by key possession, and the row itself is what tells
+   * the server which tenant to mint the next token for. Everything with a
+   * token (and therefore a tenant) in scope goes through {@link get}.
+   *
+   * Deliberately NOT re-exported from this package's entry point (`index.ts`
+   * exports no naked-lookup surface at all), so no embedder can turn it into
+   * a cross-tenant device oracle: the only reachable public device surface is
+   * tenant-first.
+   */
+  resolveByDeviceId(deviceId) {
+    return this.byDeviceId.get(deviceId);
+  }
+};
+var NonceStore = class {
+  nonces = /* @__PURE__ */ new Map();
+  /** Number of nonce records currently held (post-sweep). Exposed for tests only. */
+  get size() {
+    return this.nonces.size;
+  }
+  /**
+   * Drop every used or expired record. A long-lived server never calls this
+   * on a timer, so `issue()` sweeps inline — a full-Map scan is fine at
+   * reference-impl scale (single-digit nonces per device, ~5min TTL).
+   */
+  sweep(now) {
+    for (const [nonce, record] of this.nonces) {
+      if (record.used || record.expiresAt <= now) {
+        this.nonces.delete(nonce);
+      }
+    }
+  }
+  issue(deviceId) {
+    const now = Date.now();
+    this.sweep(now);
+    const nonce = randomBytes(24).toString("base64url");
+    this.nonces.set(nonce, { deviceId, expiresAt: now + NONCE_TTL_MS, used: false });
+    return nonce;
+  }
+  /** `true` iff `nonce` exists, belongs to `deviceId`, is unexpired, and hasn't been consumed yet. Does not mutate. */
+  validate(deviceId, nonce) {
+    const record = this.nonces.get(nonce);
+    if (!record) return false;
+    if (record.used) return false;
+    if (record.deviceId !== deviceId) return false;
+    if (Date.now() > record.expiresAt) return false;
+    return true;
+  }
+  /** Mark `nonce` consumed so a replay of the same (deviceId, nonce, signature) is rejected. */
+  markUsed(nonce) {
+    const record = this.nonces.get(nonce);
+    if (record) record.used = true;
+  }
+};
+function verifyEd25519Signature(devicePublicKey, message, signature) {
+  try {
+    const keyObject = createPublicKey({
+      key: { kty: "OKP", crv: "Ed25519", x: devicePublicKey },
+      format: "jwk"
+    });
+    return verify(null, Buffer.from(message, "utf8"), keyObject, Buffer.from(signature, "base64url"));
+  } catch {
+    return false;
+  }
+}
+function verifyNonceSignature(devicePublicKey, nonce, signature) {
+  return verifyEd25519Signature(devicePublicKey, NONCE_SIGNING_DOMAIN + nonce, signature);
+}
+function extractBearerToken(header) {
+  if (!header) return void 0;
+  const match = /^Bearer\s+(.+)$/i.exec(header);
+  return match?.[1];
+}
+async function authenticateBearer(header, deps) {
+  const token = extractBearerToken(header);
+  if (!token) return void 0;
+  const claims = await deps.tokenSigner.verify(token);
+  if (!claims) return void 0;
+  const device = deps.devices.get(claims.tenantId, claims.deviceId);
+  if (!device || device.revoked) return void 0;
+  if (device.productId !== claims.productId) return void 0;
+  return { deviceId: device.deviceId, tenantId: device.tenantId, productId: device.productId };
+}
+var BlobDeclarationConflictError = class extends Error {
+  constructor(blobId) {
+    super(`Blob ${blobId} already binds a different declaration.`);
+    this.name = "BlobDeclarationConflictError";
+  }
+};
+var DEFAULT_URL_TTL_MS = 15 * 60 * 1e3;
+function sha256Hex(data) {
+  return `sha256:${createHash("sha256").update(data).digest("hex")}`;
+}
+var LocalDiskBlobStore = class {
+  secret = randomBytes(32);
+  directory;
+  urlTtlMs;
+  blobs = /* @__PURE__ */ new Map();
+  ready;
+  constructor(opts = {}) {
+    this.directory = opts.directory ?? mkdtempSync(path.join(tmpdir(), "byok-blobs-"));
+    this.urlTtlMs = opts.urlTtlMs ?? DEFAULT_URL_TTL_MS;
+    this.ready = mkdir(this.directory, { recursive: true }).then(() => void 0);
+  }
+  async createUpload(input, requestedBlobId) {
+    await this.ready;
+    const blobId = requestedBlobId ?? `blob_${randomUUID()}`;
+    const existing = this.blobs.get(blobId);
+    if (existing !== void 0) {
+      if (existing.meta.size !== input.size || existing.meta.contentType !== input.contentType || existing.meta.contentHash !== input.contentHash) {
+        throw new BlobDeclarationConflictError(blobId);
+      }
+      return { blobId, uploadUrl: this.signUrl(blobId, "put") };
+    }
+    this.blobs.set(blobId, { meta: input, uploaded: false });
+    return { blobId, uploadUrl: this.signUrl(blobId, "put") };
+  }
+  async getDownloadUrl(blobId) {
+    const record = this.blobs.get(blobId);
+    if (!record?.uploaded) return void 0;
+    return this.signUrl(blobId, "get");
+  }
+  async exists(blobId) {
+    return this.blobs.get(blobId)?.uploaded ?? false;
+  }
+  verifySignedUrl(blobId, action, sig, exp) {
+    if (!Number.isFinite(exp) || Date.now() > exp) return false;
+    const expected = this.computeSig(blobId, action, exp);
+    const expectedBuf = Buffer.from(expected, "base64url");
+    const actualBuf = Buffer.from(sig, "base64url");
+    if (expectedBuf.length !== actualBuf.length) return false;
+    return timingSafeEqual(expectedBuf, actualBuf);
+  }
+  async writeContent(blobId, data) {
+    await this.ready;
+    const record = this.blobs.get(blobId);
+    if (!record) return { ok: false, reason: "unknown blobId" };
+    if (record.uploaded) return { ok: false, reason: "blob already uploaded" };
+    if (data.length !== record.meta.size) {
+      return { ok: false, reason: `size mismatch: declared ${record.meta.size}, received ${data.length}` };
+    }
+    const actualHash = sha256Hex(data);
+    if (actualHash !== record.meta.contentHash) {
+      return { ok: false, reason: "contentHash mismatch" };
+    }
+    await writeFile(this.pathFor(blobId), data);
+    record.uploaded = true;
+    return { ok: true };
+  }
+  async readContent(blobId) {
+    const record = this.blobs.get(blobId);
+    if (!record?.uploaded) return void 0;
+    const data = await readFile(this.pathFor(blobId));
+    return { data, contentType: record.meta.contentType };
+  }
+  pathFor(blobId) {
+    return path.join(this.directory, blobId);
+  }
+  computeSig(blobId, action, exp) {
+    return createHmac("sha256", this.secret).update(`${blobId}:${action}:${exp}`).digest("base64url");
+  }
+  signUrl(blobId, action) {
+    const exp = Date.now() + this.urlTtlMs;
+    const sig = this.computeSig(blobId, action, exp);
+    return `/byok/blobs/${blobId}/content?sig=${sig}&exp=${exp}`;
+  }
+};
+var PAIRING_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+function generatePairingCode(length = 8) {
+  const bytes = randomBytes(length);
+  let out = "";
+  for (let i = 0; i < length; i++) {
+    out += PAIRING_CODE_ALPHABET[bytes[i] % PAIRING_CODE_ALPHABET.length];
+  }
+  return out;
+}
+function generateDeviceId() {
+  return `dev_${randomUUID()}`;
+}
+function generateTaskId() {
+  return `task_${randomUUID()}`;
+}
+
+// src/pairing.ts
+var PAIRING_CODE_TTL_MS = 10 * 60 * 1e3;
+var PairingCodeInvalidError = class extends Error {
+  constructor(reason) {
+    super(`invalid pairing code: ${reason}`);
+    this.name = "PairingCodeInvalidError";
+  }
+};
+var PairingManager = class {
+  codes = /* @__PURE__ */ new Map();
+  /**
+   * Mint a single-use code bound to `claims`. Claims are REQUIRED — a
+   * claimless mint is a compile error, and (for a JS caller, or a claims
+   * object assembled from untyped config) a runtime {@link TypeError}. There
+   * is no default tenant and no default product: a device with no tenant
+   * must be inexpressible, so the failure happens here, at the mint, rather
+   * than being filled in downstream.
+   */
+  createPairingCode(claims) {
+    const validated = validatePairingCodeClaims(claims);
+    const code = generatePairingCode();
+    const expiresAt = Date.now() + PAIRING_CODE_TTL_MS;
+    this.codes.set(code, { code, claims: validated, expiresAt, used: false });
+    return { code, expiresAt: new Date(expiresAt).toISOString() };
+  }
+  /**
+   * Validate and consume a pairing code, returning the {@link PairingCodeClaims}
+   * it was minted with. Throws {@link PairingCodeInvalidError} if the code is
+   * unknown, expired, or already used — callers (the HTTP handler) map that to
+   * a 401. Single-use is what makes the caller's "redeem, then register the
+   * device row with these claims" sequence safe: a second redeem of the same
+   * code can never reach the registration step at all.
+   */
+  redeemPairingCode(code) {
+    const record = this.codes.get(code);
+    if (!record) {
+      throw new PairingCodeInvalidError("unknown code");
+    }
+    if (record.used) {
+      throw new PairingCodeInvalidError("code already used");
+    }
+    if (Date.now() > record.expiresAt) {
+      throw new PairingCodeInvalidError("code expired");
+    }
+    record.used = true;
+    return record.claims;
+  }
+};
+function validatePairingCodeClaims(claims) {
+  if (typeof claims !== "object" || claims === null) {
+    throw new TypeError("createPairingCode requires { tenantId, productId } claims");
+  }
+  const { tenantId, productId } = claims;
+  if (typeof tenantId !== "string" || tenantId.length === 0) {
+    throw new TypeError("createPairingCode requires a non-empty tenantId");
+  }
+  if (typeof productId !== "string" || productId.length === 0) {
+    throw new TypeError("createPairingCode requires a non-empty productId");
+  }
+  return { tenantId, productId };
+}
+
+// src/http.ts
+async function readJsonBody(c) {
+  try {
+    return await c.req.json();
+  } catch {
+    return void 0;
+  }
+}
+function buildHonoApp(deps) {
+  const app = new Hono();
+  const serverStartedAtMs = Date.now();
+  if (deps.healthzRoute) {
+    app.get("/healthz", (c) => c.json({ ok: true, uptimeMs: Date.now() - serverStartedAtMs }, 200));
+  }
+  app.post("/byok/pair", async (c) => {
+    const parsed = PairRequestSchema.safeParse(await readJsonBody(c));
+    if (!parsed.success) {
+      return c.json({ error: "pairingCode, deviceName, and devicePublicKey are required strings" }, 400);
+    }
+    const { pairingCode, deviceName, devicePublicKey } = parsed.data;
+    let claims;
+    try {
+      claims = deps.pairing.redeemPairingCode(pairingCode);
+    } catch (err) {
+      if (err instanceof PairingCodeInvalidError) {
+        return c.json({ error: err.message }, 401);
+      }
+      throw err;
+    }
+    const deviceId = generateDeviceId();
+    deps.devices.register({
+      tenantId: claims.tenantId,
+      productId: claims.productId,
+      deviceId,
+      deviceName,
+      devicePublicKey
+    });
+    const { accessToken, expiresAt } = await mintAccessToken(deps.tokenSigner, {
+      deviceId,
+      tenantId: claims.tenantId,
+      productId: claims.productId
+    });
+    const response = { deviceId, accessToken, refreshHint: expiresAt };
+    return c.json(response, 200);
+  });
+  app.post("/byok/challenge", async (c) => {
+    const parsed = ChallengeRequestSchema.safeParse(await readJsonBody(c));
+    if (!parsed.success) return c.json({ error: "deviceId is required" }, 400);
+    const { deviceId } = parsed.data;
+    const device = deps.devices.resolveByDeviceId(deviceId);
+    if (!device || device.revoked) {
+      return c.json({ error: "unknown or revoked device" }, 401);
+    }
+    const nonce = deps.nonces.issue(deviceId);
+    const response = { nonce };
+    return c.json(response, 200);
+  });
+  app.post("/byok/token", async (c) => {
+    const parsed = TokenRequestSchema.safeParse(await readJsonBody(c));
+    if (!parsed.success) return c.json({ error: "deviceId, nonce, and signature are required" }, 400);
+    const { deviceId, nonce, signature } = parsed.data;
+    const device = deps.devices.resolveByDeviceId(deviceId);
+    if (!device || device.revoked) {
+      return c.json({ error: "unknown or revoked device" }, 401);
+    }
+    if (!deps.nonces.validate(deviceId, nonce)) {
+      return c.json({ error: "invalid, expired, or already-used nonce" }, 401);
+    }
+    if (!verifyNonceSignature(device.devicePublicKey, nonce, signature)) {
+      return c.json({ error: "invalid signature" }, 401);
+    }
+    deps.nonces.markUsed(nonce);
+    const { accessToken, expiresAt } = await mintAccessToken(deps.tokenSigner, {
+      deviceId: device.deviceId,
+      tenantId: device.tenantId,
+      productId: device.productId
+    });
+    const response = { accessToken, expiresAt };
+    return c.json(response, 200);
+  });
+  app.post("/byok/blobs", async (c) => {
+    const principal = await authenticateBearer(c.req.header("authorization"), deps);
+    if (!principal) return c.json({ error: "unauthorized" }, 401);
+    const parsed = CreateBlobRequestSchema.safeParse(await readJsonBody(c));
+    if (!parsed.success) return c.json({ error: "size, contentType, and contentHash are required" }, 400);
+    if (parsed.data.size > deps.maxBlobSizeBytes) {
+      return c.json({ error: `blob exceeds max size of ${deps.maxBlobSizeBytes} bytes` }, 413);
+    }
+    const reservationId = c.req.header("idempotency-key");
+    if (!reservationId || reservationId.length > 200) {
+      return c.json({ error: "Idempotency-Key header is required" }, 400);
+    }
+    const blobId = reservationBlobId(principal.tenantId, reservationId);
+    try {
+      const created = await deps.blobStore.createUpload(parsed.data, blobId);
+      const response = created;
+      return c.json(response, 200);
+    } catch (error) {
+      if (error instanceof BlobDeclarationConflictError) {
+        return c.json({ error: "storage_integrity_mismatch" }, 422);
+      }
+      throw error;
+    }
+  });
+  app.post("/byok/blobs/:id/finalize", async (c) => {
+    const principal = await authenticateBearer(c.req.header("authorization"), deps);
+    if (!principal) return c.json({ error: "unauthorized" }, 401);
+    const reservationId = c.req.header("idempotency-key");
+    if (!reservationId || reservationId.length > 200) {
+      return c.json({ error: "Idempotency-Key header is required" }, 400);
+    }
+    const blobId = c.req.param("id");
+    if (reservationBlobId(principal.tenantId, reservationId) !== blobId) {
+      return c.json({ error: "storage_integrity_mismatch" }, 422);
+    }
+    if (!await deps.blobStore.exists(blobId)) {
+      return c.json({ error: "storage_reservation_not_found" }, 404);
+    }
+    return c.body(null, 204);
+  });
+  app.get("/byok/blobs/:id/url", async (c) => {
+    const principal = await authenticateBearer(c.req.header("authorization"), deps);
+    if (!principal) return c.json({ error: "unauthorized" }, 401);
+    const downloadUrl = await deps.blobStore.getDownloadUrl(c.req.param("id"));
+    if (!downloadUrl) return c.json({ error: "blob not found" }, 404);
+    const response = { downloadUrl };
+    return c.json(response, 200);
+  });
+  app.put("/byok/blobs/:id/content", async (c) => {
+    const blobId = c.req.param("id");
+    const { sig, exp } = signedUrlParams(c.req.query("sig"), c.req.query("exp"));
+    if (!sig || exp === void 0 || !deps.blobStore.verifySignedUrl(blobId, "put", sig, exp)) {
+      return c.json({ error: "invalid or expired signature" }, 401);
+    }
+    const data = Buffer.from(await c.req.arrayBuffer());
+    const result = await deps.blobStore.writeContent(blobId, data);
+    if (!result.ok) return c.json({ error: result.reason }, 422);
+    return c.body(null, 204);
+  });
+  app.get("/byok/blobs/:id/content", async (c) => {
+    const blobId = c.req.param("id");
+    const { sig, exp } = signedUrlParams(c.req.query("sig"), c.req.query("exp"));
+    if (!sig || exp === void 0 || !deps.blobStore.verifySignedUrl(blobId, "get", sig, exp)) {
+      return c.json({ error: "invalid or expired signature" }, 401);
+    }
+    const content = await deps.blobStore.readContent(blobId);
+    if (!content) return c.json({ error: "blob not found" }, 404);
+    return c.body(new Uint8Array(content.data), 200, { "content-type": content.contentType });
+  });
+  app.get("/byok/events", async (c) => {
+    const principal = await authenticateBearer(c.req.header("authorization"), deps);
+    if (!principal) return c.json({ error: "unauthorized" }, 401);
+    const cursorRaw = c.req.query("cursor");
+    let cursor = 0;
+    if (cursorRaw !== void 0) {
+      const parsedCursor = Number(cursorRaw);
+      if (!Number.isInteger(parsedCursor) || parsedCursor < 0) return c.json({ error: "invalid cursor" }, 400);
+      cursor = parsedCursor;
+    }
+    const result = await deps.hub.pollEvents(principal.deviceId, cursor, deps.longPollHoldMs);
+    const response = result;
+    return c.json(response, 200);
+  });
+  app.post("/byok/messages", async (c) => {
+    const principal = await authenticateBearer(c.req.header("authorization"), deps);
+    if (!principal) return c.json({ error: "unauthorized" }, 401);
+    const parsed = MessagesSendRequestSchema.safeParse(await readJsonBody(c));
+    if (!parsed.success) return c.json({ error: "messages must be an array of envelopes" }, 400);
+    let accepted = 0;
+    let rejected = 0;
+    for (const envelope of parsed.data.messages) {
+      const result = deps.hub.handleInbound(principal.deviceId, envelope);
+      if (result === "rate_limited") {
+        return c.json({ error: "rate limit exceeded" }, 429);
+      }
+      if (result === "rejected") rejected++;
+      else accepted++;
+    }
+    const response = rejected > 0 ? { accepted, rejected } : { accepted };
+    return c.json(response, 200);
+  });
+  return app;
+}
+function reservationBlobId(tenantId, reservationId) {
+  return `blob_${createHash("sha256").update(`${tenantId}\0${reservationId}`).digest("hex")}`;
+}
+function signedUrlParams(sig, expRaw) {
+  if (!sig || expRaw === void 0) return {};
+  const exp = Number(expRaw);
+  if (!Number.isFinite(exp)) return {};
+  return { sig, exp };
+}
+
+// src/event-queue.ts
+var AsyncEventQueue = class {
+  buffer = [];
+  closed = false;
+  waiters = [];
+  push(value) {
+    if (this.closed) return;
+    this.buffer.push(value);
+    this.wake();
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.wake();
+  }
+  wake() {
+    const waiters = this.waiters;
+    this.waiters = [];
+    for (const resolve of waiters) resolve();
+  }
+  waitForMore() {
+    return new Promise((resolve) => this.waiters.push(resolve));
+  }
+  /** Async-iterate the buffer from index 0, waiting for new pushes until closed. */
+  subscribe() {
+    const queue = this;
+    return {
+      [Symbol.asyncIterator]() {
+        let index = 0;
+        return {
+          async next() {
+            for (; ; ) {
+              if (index < queue.buffer.length) {
+                return { value: queue.buffer[index++], done: false };
+              }
+              if (queue.closed) {
+                return { value: void 0, done: true };
+              }
+              await queue.waitForMore();
+            }
+          }
+        };
+      }
+    };
+  }
+};
+
+// src/rate-limiter.ts
+var DEFAULT_MESSAGES_PER_SECOND = 50;
+var DEFAULT_BURST = 100;
+var DEFAULT_MAX_TRACKED_DEVICES = 1e4;
+var EVICTION_SWEEP_EVERY_N_CALLS = 1e3;
+var RateLimiter = class {
+  messagesPerSecond;
+  burst;
+  buckets = /* @__PURE__ */ new Map();
+  /**
+   * Wall-clock idle duration (ms) after which a bucket is GUARANTEED to
+   * already be refilled to `burst`, regardless of its actual token count at
+   * last touch — i.e. the time to go from 0 tokens to `burst` at this
+   * instance's configured rate. `evictIdleBucketsIfDue` uses this as the
+   * eviction threshold: dropping an entry idle at least this long and
+   * recreating it fresh (tokens = burst) on the next `consume()` is
+   * therefore behaviorally IDENTICAL to refilling it in place would have
+   * been — both cap at `burst` — so eviction is semantically invisible to
+   * the caller.
+   */
+  idleEvictionThresholdMs;
+  /** Finding R5: hard cap on `buckets.size` — see {@link DEFAULT_MAX_TRACKED_DEVICES}'s own doc comment. */
+  maxTrackedDevices;
+  /** Calls to `consume()` since the last sweep — see `EVICTION_SWEEP_EVERY_N_CALLS`. */
+  callsSinceSweep = 0;
+  constructor(opts = {}) {
+    const messagesPerSecond = opts.messagesPerSecond ?? DEFAULT_MESSAGES_PER_SECOND;
+    const burst = opts.burst ?? DEFAULT_BURST;
+    const maxTrackedDevices = opts.maxTrackedDevices ?? DEFAULT_MAX_TRACKED_DEVICES;
+    if (!Number.isFinite(messagesPerSecond) || messagesPerSecond <= 0) {
+      throw new TypeError(`RateLimiter: messagesPerSecond must be a finite number > 0, got ${messagesPerSecond}`);
+    }
+    if (!Number.isFinite(burst) || burst < 1) {
+      throw new TypeError(`RateLimiter: burst must be a finite number >= 1, got ${burst}`);
+    }
+    if (!Number.isFinite(maxTrackedDevices) || maxTrackedDevices < 1) {
+      throw new TypeError(`RateLimiter: maxTrackedDevices must be a finite number >= 1, got ${maxTrackedDevices}`);
+    }
+    this.messagesPerSecond = messagesPerSecond;
+    this.burst = burst;
+    this.maxTrackedDevices = maxTrackedDevices;
+    this.idleEvictionThresholdMs = burst / messagesPerSecond * 1e3;
+  }
+  /**
+   * Debit one token from `key`'s bucket, refilling first for however much
+   * wall-clock time has elapsed since its last refill. Returns `false`
+   * (and debits nothing) when the bucket is currently empty — the caller is
+   * over budget right now.
+   */
+  consume(key) {
+    const now = Date.now();
+    this.evictIdleBucketsIfDue(now);
+    let bucket = this.buckets.get(key);
+    if (!bucket) {
+      this.evictOldestIfAtCapacity();
+      bucket = { tokens: this.burst, lastRefillMs: now };
+      this.buckets.set(key, bucket);
+    } else {
+      const elapsedMs = now - bucket.lastRefillMs;
+      if (elapsedMs > 0) {
+        bucket.tokens = Math.min(this.burst, bucket.tokens + elapsedMs / 1e3 * this.messagesPerSecond);
+        bucket.lastRefillMs = now;
+      }
+    }
+    if (bucket.tokens < 1) return false;
+    bucket.tokens -= 1;
+    return true;
+  }
+  /**
+   * Every `EVICTION_SWEEP_EVERY_N_CALLS` calls to `consume()`, drops every
+   * bucket idle for at least `idleEvictionThresholdMs` (see that field's doc
+   * comment for why this is safe). Without this, `buckets` would hold one
+   * permanent entry per historical key forever — every device that ever
+   * connected, even long after it disconnected for good — growing without
+   * bound over a long-lived server's lifetime.
+   */
+  evictIdleBucketsIfDue(now) {
+    this.callsSinceSweep++;
+    if (this.callsSinceSweep < EVICTION_SWEEP_EVERY_N_CALLS) return;
+    this.callsSinceSweep = 0;
+    for (const [key, bucket] of this.buckets) {
+      if (now - bucket.lastRefillMs >= this.idleEvictionThresholdMs) {
+        this.buckets.delete(key);
+      }
+    }
+  }
+  /**
+   * Finding R5 (cross-model re-review — F10 residual): called right before
+   * inserting a bucket for a genuinely NEW key, evicting the single
+   * LEAST-RECENTLY-refilled entry if `buckets` is already at
+   * `maxTrackedDevices` — an O(n) scan, but one that only ever runs once
+   * the map is already at its hard ceiling (a rare/bounded event under
+   * ordinary operation, not a per-call cost), mirroring this codebase's own
+   * established "acceptable O(n) for a rare/bounded case" precedent (e.g.
+   * `audit-log.ts`'s `compactPreservingLiveTasks` during rotation).
+   *
+   * Equivalence split (stated explicitly, not left implied):
+   * - For any evicted bucket that was ALREADY idle for at least
+   *   `idleEvictionThresholdMs` (i.e. `evictIdleBucketsIfDue` would have
+   *   reclaimed it anyway, just not yet — sweeps only run every
+   *   `EVICTION_SWEEP_EVERY_N_CALLS` calls, not continuously), eviction is
+   *   PROVABLY equivalent to an in-place refill: both cap at `burst`, so a
+   *   caller can never observe the difference (see `idleEvictionThresholdMs`'s
+   *   own doc comment for the identical reasoning `evictIdleBucketsIfDue`
+   *   already relies on).
+   * - For a bucket evicted EARLY — still within its idle threshold, forced
+   *   out only because `buckets` is at capacity (many thousands of
+   *   genuinely-distinct, actively-used keys, not a quiet one) — this is
+   *   BEST-EFFORT, not equivalence-preserving: whatever partial token debt
+   *   that key had is discarded, and its very next `consume()` call starts
+   *   completely fresh (`tokens: this.burst`), a strictly MORE permissive
+   *   outcome than if it had kept its place. This is an accepted,
+   *   deliberately bounded trade-off — it only ever engages under
+   *   cardinality far beyond any plausible real deployment — favoring
+   *   bounded memory over perfect per-key continuity in that one extreme
+   *   case.
+   */
+  evictOldestIfAtCapacity() {
+    if (this.buckets.size < this.maxTrackedDevices) return;
+    let oldestKey;
+    let oldestLastRefillMs = Infinity;
+    for (const [key, bucket] of this.buckets) {
+      if (bucket.lastRefillMs < oldestLastRefillMs) {
+        oldestLastRefillMs = bucket.lastRefillMs;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey !== void 0) this.buckets.delete(oldestKey);
+  }
+};
+
+// src/hub.ts
+var DEFAULT_POLICY = { mode: "confirm" };
+var OUTBOX_RING_CAPACITY = 500;
+var DEDUP_RING_CAPACITY = 1024;
+var MAX_LEASE_REAPER_SWEEP_INTERVAL_MS = 3e4;
+function isTerminal(state) {
+  return state === "Complete" || state === "Failed" || state === "Cancelled";
+}
+function isClaimedState(state) {
+  return state === "Claimed" || state === "Running" || state === "AwaitApproval";
+}
+var UnknownTaskError = class extends Error {
+  constructor(taskId) {
+    super(`unknown taskId: ${taskId}`);
+    this.taskId = taskId;
+    this.name = "UnknownTaskError";
+  }
+  taskId;
+};
+var TaskNotAwaitingApprovalError = class extends Error {
+  constructor(taskId, state, verb) {
+    super(`cannot ${verb} task ${taskId}: not awaiting approval (state ${state})`);
+    this.taskId = taskId;
+    this.state = state;
+    this.name = "TaskNotAwaitingApprovalError";
+  }
+  taskId;
+  state;
+};
+var StaleApprovalError = class extends Error {
+  constructor(taskId, requestedApprovalId, currentApprovalId) {
+    super(
+      `cannot resolve approval ${requestedApprovalId} for task ${taskId}: the currently pending approval is ${currentApprovalId ?? "(none recorded)"}`
+    );
+    this.taskId = taskId;
+    this.requestedApprovalId = requestedApprovalId;
+    this.currentApprovalId = currentApprovalId;
+    this.name = "StaleApprovalError";
+  }
+  taskId;
+  requestedApprovalId;
+  currentApprovalId;
+};
+function steerRejectionMessage(taskId, code, state, runtime) {
+  switch (code) {
+    case "task_terminal":
+      return `cannot steer task ${taskId}: task is already terminal (state ${state})`;
+    case "task_not_running":
+      return `cannot steer task ${taskId}: not running (state ${state})`;
+    case "steer_unsupported_runtime":
+      return `cannot steer task ${taskId}: claimed runtime ${runtime ?? "(unknown)"} does not support steering`;
+  }
+}
+var SteerRejectedError = class extends Error {
+  constructor(taskId, code, state, runtime) {
+    super(steerRejectionMessage(taskId, code, state, runtime));
+    this.taskId = taskId;
+    this.code = code;
+    this.state = state;
+    this.runtime = runtime;
+    this.name = "SteerRejectedError";
+  }
+  taskId;
+  code;
+  state;
+  runtime;
+};
+var ConnectionHub = class {
+  constructor(taskStore, devices, taskLeaseMs, rateLimiter = new RateLimiter()) {
+    this.taskStore = taskStore;
+    this.devices = devices;
+    this.taskLeaseMs = taskLeaseMs;
+    this.rateLimiter = rateLimiter;
+    const sweepIntervalMs = Math.min(Math.max(taskLeaseMs, 10), MAX_LEASE_REAPER_SWEEP_INTERVAL_MS);
+    this.leaseReaperTimer = setInterval(() => this.sweepLeases(), sweepIntervalMs);
+    this.leaseReaperTimer.unref?.();
+  }
+  taskStore;
+  devices;
+  taskLeaseMs;
+  rateLimiter;
+  connections = /* @__PURE__ */ new Map();
+  outboxes = /* @__PURE__ */ new Map();
+  /** Idempotency window per device (N3) — recent inbound envelope ids, capped at {@link DEDUP_RING_CAPACITY}. */
+  dedupRings = /* @__PURE__ */ new Map();
+  longPollWaiters = /* @__PURE__ */ new Map();
+  runtimes = /* @__PURE__ */ new Map();
+  serverEvents = new AsyncEventQueue();
+  /**
+   * Per-task last-inbound-activity timestamp (epoch ms) — the task-lease
+   * reaper's condition (c), see the "task-lease reaper" section below. Reset
+   * on every accepted inbound `task.*` envelope ({@link recordTaskActivity},
+   * called from {@link dispatchToHandler}); cleared once the task reaches a
+   * terminal state ({@link onStateChange}), so this map only ever holds
+   * entries for currently non-terminal claimed tasks.
+   */
+  taskActivity = /* @__PURE__ */ new Map();
+  /** The task-lease reaper's own periodic sweep timer — see the constructor and `sweepLeases` below. */
+  leaseReaperTimer;
+  /** {@link ConnectionHub.stats}'s `uptimeMs` origin — this hub's own construction instant. */
+  startedAtMs = Date.now();
+  /** {@link ConnectionHub.stats}'s `envelopesIn` — every {@link handleInbound} call, every outcome. */
+  envelopesInCount = 0;
+  /** {@link ConnectionHub.stats}'s `envelopesOut` — every envelope built via the single outbound choke point, {@link sendToDevice}. */
+  envelopesOutCount = 0;
+  /** {@link ConnectionHub.stats}'s `dedupDrops` (N3). */
+  dedupDropCount = 0;
+  /** {@link ConnectionHub.stats}'s `rateLimitEvents` — see {@link handleRateLimited}. */
+  rateLimitEventCount = 0;
+  /**
+   * M4 Phase 4 (gatekeeper LOW advisory): devices that have already had a
+   * `device.rate_limited` embedder event emitted for their CURRENT
+   * over-budget episode — see {@link handleRateLimited}'s own doc comment.
+   * Coalescing state only; {@link rateLimitEventCount} still counts every
+   * single hit regardless of what this suppresses.
+   */
+  rateLimitEventEmittedFor = /* @__PURE__ */ new Set();
+  /**
+   * Stop the task-lease reaper's sweep timer — called by `ByokServer.stop()`
+   * (`index.ts`) on shutdown. Idempotent: clearing an already-cleared
+   * interval is a safe no-op.
+   */
+  stopLeaseReaper() {
+    clearInterval(this.leaseReaperTimer);
+  }
+  /** The top-level `events` feed returned by `createByokServer` — see {@link ByokServerEvent}. */
+  subscribeServerEvents() {
+    return this.serverEvents.subscribe();
+  }
+  // ---------------------------------------------------------------------
+  // connection lifecycle — called from ws-server.ts / http.ts
+  // ---------------------------------------------------------------------
+  /**
+   * A daemon completed the WS handshake (`conn.hello`). Does not itself send
+   * `conn.ack` or redeliver — see {@link sendConnAck}/{@link redeliverAfterReconnect}.
+   *
+   * `capabilities` (M5, hello-capability plumbing): the daemon's own
+   * `conn.hello.capabilities` — previously silently ignored end to end (a
+   * verified gap: `ws-server.ts` forwarded only `runtimes`). Optional so
+   * every pre-M5 direct-construction call site (several tests construct a
+   * `ConnectionHub` and call this directly) keeps working unchanged; a
+   * connection this hub never learns capabilities for simply reads back
+   * `undefined` from {@link getDeviceCapabilities}.
+   */
+  registerConnection(deviceId, ws, runtimes, capabilities) {
+    const at = (/* @__PURE__ */ new Date()).toISOString();
+    this.connections.set(deviceId, { ws, connected: true, lastSeen: at, runtimes, capabilities });
+    this.serverEvents.push({ kind: "device.connected", deviceId, at });
+    this.settleLongPollWaiter(deviceId);
+  }
+  sendConnAck(deviceId, capabilities) {
+    this.sendToDevice(
+      deviceId,
+      "conn.ack",
+      {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities,
+        serverTime: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      {}
+      // conn.ack needs neither taskId nor sessionRef
+    );
+  }
+  /**
+   * Reconnection procedure step 3 (§9): redeliver, in `seq` order, every
+   * retained envelope with `seq > cursor` that still belongs to a
+   * non-terminal task. Called after `conn.ack` (step 2), per the spec.
+   */
+  redeliverAfterReconnect(deviceId, cursor) {
+    const conn = this.connections.get(deviceId);
+    if (!conn?.ws || !conn.connected) return;
+    for (const envelope of this.collectRelevant(deviceId, cursor)) {
+      conn.ws.send(encodeEnvelope(envelope));
+    }
+  }
+  /**
+   * A device's WS socket closed. `ws` identifies *which* socket closed: if
+   * it's no longer the one this device's connection state points at (a
+   * newer WS reconnected, or long-poll took over — "last transport wins"),
+   * this close is for a stale/superseded socket and the device isn't
+   * actually gone, so the bookkeeping below is skipped entirely.
+   *
+   * M1 note: the M0 server force-failed/cancelled every in-flight task for a
+   * device the instant it disconnected, on the stated premise that "a task
+   * still in flight for a device that just disconnected can't be resumed, so
+   * it's terminated" — true only in the absence of a redelivery cursor. M1
+   * adds exactly that (§9): a task's in-flight state is retained
+   * independently of any one connection, specifically so it can survive a
+   * disconnect and resume via redelivery once the device reconnects. Failing
+   * tasks here would make that feature unreachable in practice (nothing
+   * would ever still be non-terminal by the time a reconnect happened), so
+   * this now only updates connection bookkeeping and leaves task state
+   * alone. A task left in-flight by a device that never reconnects stays
+   * that way until the SaaS embedder explicitly cancels it — no
+   * disconnect-timeout is specified by the protocol, so none is invented
+   * here (see the M1-2 report's contract-gap notes).
+   */
+  handleDisconnect(deviceId, ws) {
+    const conn = this.connections.get(deviceId);
+    if (!conn || conn.ws !== ws) return;
+    conn.connected = false;
+    conn.ws = void 0;
+    conn.lastSeen = (/* @__PURE__ */ new Date()).toISOString();
+    conn.darkSince = Date.now();
+    this.serverEvents.push({ kind: "device.disconnected", deviceId, at: conn.lastSeen });
+    this.settleLongPollWaiter(deviceId);
+  }
+  // ---------------------------------------------------------------------
+  // long-poll fallback (§8) — GET /byok/events, called from http.ts
+  // ---------------------------------------------------------------------
+  /**
+   * Resolve immediately if there are already-relevant events past `cursor`;
+   * otherwise hold for up to `holdMs` and resolve with an empty result if
+   * nothing arrives. A device may be connected via WS or long-poll, not
+   * both simultaneously — a poll here supersedes (closes) any live WS for
+   * this device ("last one wins", documented at the type level on
+   * {@link ConnectionState}).
+   */
+  async pollEvents(deviceId, cursor, holdMs) {
+    this.takeOverAsLongPoll(deviceId);
+    this.settleLongPollWaiter(deviceId);
+    const immediate = this.collectRelevant(deviceId, cursor);
+    if (immediate.length > 0) {
+      return { events: immediate, cursor: this.currentCursor(deviceId) };
+    }
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.longPollWaiters.delete(deviceId);
+        resolve({ events: [], cursor: this.currentCursor(deviceId) });
+      }, holdMs);
+      timer.unref?.();
+      this.longPollWaiters.set(deviceId, { cursor, resolve, timer });
+    });
+  }
+  /** Make long-poll this device's active transport, closing any live WS ("last one wins", §8). */
+  takeOverAsLongPoll(deviceId) {
+    const conn = this.connections.get(deviceId);
+    const at = (/* @__PURE__ */ new Date()).toISOString();
+    const wasFreshlyConnected = !conn || conn.ws !== void 0 || !conn.connected;
+    if (conn?.ws) {
+      const ws = conn.ws;
+      this.connections.set(deviceId, { connected: true, lastSeen: at, runtimes: conn.runtimes, capabilities: conn.capabilities });
+      ws.close(1e3, "superseded by long-poll connection");
+    } else if (!conn) {
+      this.connections.set(deviceId, { connected: true, lastSeen: at });
+    } else {
+      conn.connected = true;
+      conn.lastSeen = at;
+      conn.darkSince = void 0;
+    }
+    if (wasFreshlyConnected) {
+      this.serverEvents.push({ kind: "device.connected", deviceId, at });
+    }
+  }
+  /** Resolve (settle) any long-poll request currently held open for `deviceId`, if one exists. */
+  settleLongPollWaiter(deviceId) {
+    const waiter = this.longPollWaiters.get(deviceId);
+    if (!waiter) return;
+    this.longPollWaiters.delete(deviceId);
+    clearTimeout(waiter.timer);
+    waiter.resolve({ events: this.collectRelevant(deviceId, waiter.cursor), cursor: this.currentCursor(deviceId) });
+  }
+  // ---------------------------------------------------------------------
+  // inbound envelopes from a connected daemon
+  // ---------------------------------------------------------------------
+  /**
+   * Single inbound choke point for every daemon -> server envelope (N2/N3/
+   * P2) — called by both the WS path (`ws-server.ts`) and the long-poll send
+   * path (`POST /byok/messages`, `http.ts`) in place of reaching into
+   * per-type handlers directly. Runs a fixed gate, in order:
+   *
+   * 0. **rate limit (M4 Phase 4, part A)** — one token debited from this
+   *    device's bucket ({@link rateLimiter}) for EVERY inbound envelope,
+   *    before anything else runs (including the type-allow check below) —
+   *    a flood of garbage-typed envelopes must cost the same budget as a
+   *    flood of well-formed ones. Checked first specifically so an
+   *    over-budget device is turned away as cheaply as possible, before any
+   *    taskStore lookup or dedup bookkeeping. See {@link handleRateLimited}
+   *    for what happens on exceed (never a silent drop).
+   * 1. **type-allow (P2)** — only {@link DAEMON_TO_SERVER_TYPES} may pass; a
+   *    server -> daemon type (or anything unrecognized, e.g. a stale/future
+   *    `conn.hello` outside the handshake) arriving inbound is rejected
+   *    before it's dispatched or counted accepted.
+   * 2. **ownership (N2)** — an envelope for a task already owned by a
+   *    *different* device is dropped (logged), never force-failed:
+   *    force-failing on an authz mismatch would let an attacker who merely
+   *    guesses a `taskId` kill the real owner's task (a DoS). A task with no
+   *    owner yet, or that doesn't exist at all, is not rejected here — the
+   *    per-type handler's own no-op-on-missing-record behavior covers the
+   *    latter.
+   * 3. **dedup (N3)** — an envelope `id` already seen from this device is a
+   *    no-op: the wire is at-least-once (§9), this makes server-side
+   *    processing at-most-once. Check-and-record is synchronous (Node is
+   *    single-threaded), so it's atomic with respect to any other envelope
+   *    for this device.
+   * 4. **dispatch** — handed to the existing per-type `on*` handler.
+   *
+   * Returns which outcome applied. A duplicate still counts as `accepted` on
+   * the `POST /byok/messages` wire (§8.2) — an idempotent replay is a
+   * wire-level success even though no handler ran a second time; only
+   * `rejected`/`rate_limited` (gate steps 0-2) are excluded from that count.
+   */
+  handleInbound(deviceId, envelope) {
+    this.envelopesInCount++;
+    if (!this.rateLimiter.consume(deviceId)) {
+      this.handleRateLimited(deviceId);
+      return "rate_limited";
+    }
+    this.rateLimitEventEmittedFor.delete(deviceId);
+    if (!DAEMON_TO_SERVER_TYPES.includes(envelope.type)) {
+      return "rejected";
+    }
+    const taskId = envelope.task_id;
+    if (taskId === void 0) return "rejected";
+    const record = this.taskStore.get(taskId);
+    if (record && record.deviceId !== void 0 && record.deviceId !== deviceId) {
+      console.warn(`[byok/server] dropping ${envelope.type} for ${taskId}: owned by a different device`);
+      return "rejected";
+    }
+    if (this.checkAndRecordDuplicate(deviceId, envelope.id)) {
+      this.dedupDropCount++;
+      return "duplicate";
+    }
+    this.dispatchToHandler(deviceId, taskId, envelope);
+    return "accepted";
+  }
+  /**
+   * M4 Phase 4 (part A): `deviceId` just exceeded its inbound-envelope rate
+   * limit. Never a silent drop: counts the occurrence
+   * ({@link rateLimitEventCount}, surfaced via {@link stats} — every single
+   * hit, unconditionally) and, the FIRST time in this over-budget episode
+   * only, emits an embedder-facing `device.rate_limited`
+   * {@link ByokServerEvent} — see that variant's own doc comment (`types.ts`)
+   * for the full per-transport enforcement shape.
+   *
+   * Gatekeeper LOW advisory (event amplification): a single flood can make
+   * `handleInbound` call this many times in a row — e.g. several WS frames
+   * already in flight before the close below actually lands, or a
+   * long-poll device retrying its `POST /byok/messages` before its bucket
+   * has refilled. Without coalescing, an embedder subscribed to
+   * `events.subscribe()` would see one `device.rate_limited` per hit, which
+   * is noisy for what is really ONE ongoing episode of one device
+   * flooding. `rateLimitEventEmittedFor` suppresses the repeats: this
+   * method only pushes the event the first time it sees a given `deviceId`
+   * since `handleInbound`'s own success path last cleared it (i.e. since
+   * this device was last confirmed back under budget) — the COUNTER above
+   * is entirely unaffected by this and still increments on every call,
+   * unconditionally.
+   *
+   * This method only handles the WS half of the enforcement shape (closing
+   * the live connection, if any, so the client's existing backoff+reconnect
+   * takes over — mirrors `takeOverAsLongPoll`'s own `ws.close`, the only
+   * other place this hub closes a device's socket directly); a long-poll
+   * device has no live `ws` to close here at all (`conn.ws` is `undefined`
+   * while long-polling — see {@link ConnectionState}), so `http.ts`'s
+   * `/byok/messages` handler maps this same `'rate_limited'` `handleInbound`
+   * outcome to an HTTP 429 for that transport instead.
+   */
+  handleRateLimited(deviceId) {
+    this.rateLimitEventCount++;
+    if (!this.rateLimitEventEmittedFor.has(deviceId)) {
+      this.rateLimitEventEmittedFor.add(deviceId);
+      const at = (/* @__PURE__ */ new Date()).toISOString();
+      this.serverEvents.push({ kind: "device.rate_limited", deviceId, at });
+    }
+    const conn = this.connections.get(deviceId);
+    if (conn?.ws) {
+      conn.ws.close(1008, "rate limit exceeded");
+    }
+  }
+  /**
+   * Idempotency check-and-record (N3): `true` (duplicate) if `id` was
+   * already seen for `deviceId`; otherwise records it and returns `false`.
+   * Bounded to {@link DEDUP_RING_CAPACITY} ids per device — a ring, not an
+   * unbounded set — evicting the oldest once full.
+   */
+  checkAndRecordDuplicate(deviceId, id) {
+    let seen = this.dedupRings.get(deviceId);
+    if (!seen) {
+      seen = /* @__PURE__ */ new Set();
+      this.dedupRings.set(deviceId, seen);
+    }
+    if (seen.has(id)) return true;
+    seen.add(id);
+    if (seen.size > DEDUP_RING_CAPACITY) {
+      const oldest = seen.values().next().value;
+      if (oldest !== void 0) seen.delete(oldest);
+    }
+    return false;
+  }
+  /**
+   * Route one already-gated envelope (see {@link handleInbound}) to its
+   * per-type handler. Type-allow/ownership/dedup have already run by the
+   * time this executes, so the handlers below no longer need their own
+   * device-mismatch checks — that authz decision now lives solely in
+   * `handleInbound` (N2).
+   *
+   * Also the task-lease reaper's activity checkpoint
+   * ({@link recordTaskActivity}): every envelope for a task that currently
+   * *exists and is non-terminal* counts as proof of life for `taskId`'s
+   * lease, regardless of what its per-type handler below ends up doing with
+   * it (including a no-op/stale drop) — see the "task-lease reaper" section
+   * further down for why. Deliberately gated on the record's existence and
+   * non-terminal state *here*, before dispatch: `taskActivity` must never
+   * gain an entry for a taskId that doesn't exist (a nonexistent/garbage id
+   * an authenticated-but-malicious daemon could send indefinitely — an
+   * unbounded-growth vector, since `taskId`s aren't deduped the way envelope
+   * `id`s are) or for one that's already terminal (a stale/late message for
+   * a finished task — `onStateChange` deletes the entry on the *real*
+   * terminal transition, but a stale message arriving *after* that would
+   * otherwise silently recreate it, since every per-type handler's own
+   * terminal/unknown-task guard runs — and early-returns — only *after*
+   * this would already have recorded activity).
+   */
+  dispatchToHandler(deviceId, taskId, envelope) {
+    const record = this.taskStore.get(taskId);
+    if (record && !isTerminal(record.state)) {
+      this.recordTaskActivity(taskId);
+    }
+    switch (envelope.type) {
+      case "task.claim":
+        this.onClaim(deviceId, envelope.task_id, envelope.payload);
+        return;
+      case "task.started":
+        this.onStarted(envelope.task_id, envelope.payload);
+        return;
+      case "task.decline":
+        this.onDecline(envelope.task_id, envelope.payload);
+        return;
+      case "task.progress":
+        this.onProgress(envelope.task_id, envelope.payload);
+        return;
+      case "task.artifact":
+        this.onArtifact(envelope.task_id, envelope.payload);
+        return;
+      case "task.await_approval":
+        this.onAwaitApproval(envelope.task_id, envelope.payload);
+        return;
+      case "task.complete":
+        this.onComplete(envelope.task_id, envelope.payload);
+        return;
+      case "task.fail":
+        this.onFail(envelope.task_id, envelope.payload);
+        return;
+      case "task.cancelled":
+        this.onCancelled(envelope.task_id, envelope.payload);
+        return;
+      case "task.approval_resolved":
+        this.onApprovalResolved(envelope.task_id, envelope.payload);
+        return;
+      default:
+        return;
+    }
+  }
+  /** Reset the task-lease reaper's per-task clock (condition (c) in the "task-lease reaper" section below). */
+  recordTaskActivity(taskId) {
+    this.taskActivity.set(taskId, Date.now());
+  }
+  /**
+   * Ownership (record.deviceId matching the connection's authenticated
+   * deviceId) is enforced centrally by {@link handleInbound} (N2) before this
+   * runs; only the idempotent-claim CAS and the first-claim device patch
+   * happen here.
+   *
+   * M5 (claimed runtime, docs/protocol.md §3.1): `payload.runtime` — the
+   * ACTUAL adapter the daemon selected (`TaskRunner.pickAdapter`,
+   * `packages/client`'s `task-runner.ts`) — is recorded into
+   * `TaskSnapshot.claimedRuntime` alongside the device patch, distinct from
+   * the pre-existing `TaskSnapshot.runtime` (the merely REQUESTED runtime,
+   * untouched here and set only once, at `dispatch()` time). Only ever
+   * written on the FIRST real claim: the idempotent-CAS early return above
+   * fires before this for a retried claim from a device that already owns
+   * the task, so a redelivered/retried `task.claim` can never overwrite an
+   * already-recorded `claimedRuntime` — including with a stale or absent
+   * value from an out-of-order retry.
+   *
+   * S0/D-4 (claim-time capability snapshot): `payload.capabilities` — the
+   * claiming adapter's OWN self-report, carried on this same `task.claim`
+   * (docs/protocol.md §2.4) — supplies
+   * `TaskSnapshot.claimedRuntimeCapabilities`, written in the same patch and
+   * therefore under the same write-exactly-once property as `claimedRuntime`.
+   *
+   * Taken from the payload and from nowhere else. This hub deliberately does
+   * NOT consult connection state (`conn.hello.runtimes[]`) for it — see
+   * {@link SteerRejectedError} for why that source is structurally wrong for a
+   * control decision, and that field's own doc comment (`types.ts`) for why
+   * this is snapshotted rather than read live at steer time. A claim that
+   * carries no `capabilities` (a pre-D-4 daemon) records `undefined`, which
+   * the gate reads as "unknown" and refuses.
+   */
+  onClaim(deviceId, taskId, payload) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    if (record.state === "Claimed" || record.state === "Running") return;
+    this.applyOrFail(taskId, "Claimed", {
+      deviceId,
+      claimedRuntime: payload.runtime,
+      claimedRuntimeCapabilities: payload.capabilities
+    });
+  }
+  /**
+   * `Claimed -> Running` (§3.1) — a daemon actually starting the runtime
+   * session, distinct from merely claiming. Ownership is already enforced
+   * by {@link handleInbound} (N2) before this runs.
+   */
+  onStarted(taskId, _payload) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    if (record.state === "Running") return;
+    if (isTerminal(record.state)) return;
+    this.applyOrFail(taskId, "Running", {});
+  }
+  /**
+   * `Offered -> Failed` (§3.2) — a fail-closed pre-claim rejection. Only
+   * ever legal from `Offered`; anything else is stale. Ownership is already
+   * enforced by {@link handleInbound} (N2) before this runs.
+   */
+  onDecline(taskId, payload) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    if (record.state !== "Offered") return;
+    this.applyOrFail(taskId, "Failed", {
+      result: { state: "Failed", reason: payload.reason, retryable: payload.retryable }
+    });
+  }
+  onProgress(taskId, payload) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    const resumed = this.resumeIfImplicitlyApproved(record);
+    if (resumed.state !== "Running") {
+      this.forceFailOrDrop(taskId, "task.progress received while not Running");
+      return;
+    }
+    const runtime = this.runtimes.get(taskId);
+    if (!runtime) return;
+    for (const event of payload.events) {
+      runtime.queue.push({ kind: "agent", event });
+    }
+  }
+  onArtifact(taskId, payload) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    const resumed = this.resumeIfImplicitlyApproved(record);
+    if (resumed.state !== "Running") {
+      this.forceFailOrDrop(taskId, "task.artifact received while not Running");
+      return;
+    }
+    const runtime = this.runtimes.get(taskId);
+    if (!runtime) return;
+    runtime.queue.push({ kind: "artifact", artifact: payload });
+  }
+  onAwaitApproval(taskId, payload) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    if (record.state === "AwaitApproval") {
+      if (payload.approvalId !== void 0 && payload.approvalId !== record.pendingApprovalId) {
+        this.taskStore.setPendingApprovalId?.(taskId, payload.approvalId);
+        this.runtimes.get(taskId)?.queue.push({ kind: "await_approval", summary: payload.summary });
+      }
+      return;
+    }
+    this.applyOrFail(taskId, "AwaitApproval", { pendingApprovalId: payload.approvalId });
+    const after = this.taskStore.get(taskId);
+    if (after?.state !== "AwaitApproval") return;
+    this.runtimes.get(taskId)?.queue.push({ kind: "await_approval", summary: payload.summary });
+  }
+  onComplete(taskId, payload) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    if (isTerminal(record.state)) return;
+    this.resumeIfImplicitlyApproved(record);
+    const result = {
+      state: "Complete",
+      summary: payload.summary,
+      sessionRef: payload.sessionRef,
+      artifactRefs: payload.artifactRefs
+    };
+    this.applyOrFail(taskId, "Complete", { result, sessionRef: payload.sessionRef });
+  }
+  onFail(taskId, payload) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    if (isTerminal(record.state)) return;
+    const result = { state: "Failed", reason: payload.reason, retryable: payload.retryable };
+    this.applyOrFail(taskId, "Failed", { result });
+  }
+  /**
+   * Dual-purpose on receipt (§3.3): if the server already moved this task to
+   * `Cancelled` on its own action (the common case — `cancelTask()` is
+   * authoritative immediately, §4), this is a late idempotent ack — silent,
+   * not a warning (this is the other half of the M0 gatekeeper finding this
+   * change resolves). Otherwise it's the authoritative trigger for a
+   * cancellation the daemon observed that the server didn't initiate.
+   * Ownership is already enforced by {@link handleInbound} (N2) before this
+   * runs.
+   */
+  onCancelled(taskId, payload) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    if (record.state === "Cancelled") return;
+    if (isTerminal(record.state)) return;
+    this.applyOrFail(taskId, "Cancelled", { result: { state: "Cancelled", reason: payload.reason } });
+  }
+  /**
+   * M4 (additive-minor, `task.approval_resolved`): the EXPLICIT counterpart
+   * to {@link resumeIfImplicitlyApproved} — a daemon that resolved a pending
+   * approval entirely LOCALLY now reports it immediately, instead of the
+   * server only finding out after the fact once evidence (a later
+   * `task.progress`/`task.artifact`/`task.complete`) proves it.
+   *
+   * Relationship to the implicit path (both stay, permanently — this is not
+   * a replacement): {@link resumeIfImplicitlyApproved} remains completely
+   * untouched as the fallback for (a) an old daemon that predates this
+   * message, and (b) a daemon connected to an old server that never
+   * advertised the `approval_resolved` capability flag (`version.ts`) at
+   * handshake time — in either case the daemon never sends this message at
+   * all (see `packages/client`'s `task-runner.ts`), and the server keeps
+   * inferring the resolution from evidence exactly as it did before this
+   * message existed. When THIS message does arrive first, it already moves
+   * the record out of `AwaitApproval` (see below) — so by the time any
+   * following `task.progress`/etc. reaches `onProgress`/`onArtifact`/
+   * `onComplete`, `resumeIfImplicitlyApproved`'s own `record.state !==
+   * 'AwaitApproval'` guard is already true and it no-ops, never firing its
+   * own `task.approval_resolved_implicit` event a second time for the same
+   * resolution. The two mechanisms race harmlessly: whichever one the
+   * server processes first is the one that actually performs the
+   * transition; the other is naturally inert once it runs.
+   *
+   * Three outcomes, mirroring this file's existing per-type idempotency
+   * conventions:
+   *   - `AwaitApproval` (the expected case): legal transition to `Running`
+   *     (an existing `TASK_TRANSITIONS` edge, the same one `approveTask`
+   *     itself uses) plus a `task.approval_resolved` {@link ByokServerEvent}
+   *     carrying `approvalId`/`decision`/`resolvedBy` for an embedder to
+   *     observe.
+   *   - Already `Running` (evidence — or the implicit path — already beat
+   *     this message to it): idempotent no-op, silent, mirroring
+   *     `onStarted`'s own already-running guard.
+   *   - Terminal, or a state that was never `AwaitApproval` in the first
+   *     place (`Offered`/`Claimed` — a genuinely out-of-sequence report):
+   *     stale no-op with a `console.warn`, matching this file's existing
+   *     stale-message convention (`forceFailOrDrop`, `handleInbound`'s
+   *     ownership-mismatch drop) — never force-failed, since a late/
+   *     redelivered report about a task that has already moved on is not
+   *     evidence of anything currently wrong with it.
+   *
+   * This is also the residual-race resolution the accompanying protocol/docs
+   * update documents: a SaaS decision (`approveTask`/`rejectTask`) already in
+   * flight when the local resolution happens can still land on the server
+   * FIRST and move the record to a terminal state before this message
+   * arrives — in that case this message hits the terminal branch above and
+   * is a stale no-op, exactly like any other late message for an
+   * already-terminal task. The window for that crossing is now
+   * network-latency-sized (how long this message takes to arrive), not
+   * "until the next progress message" the way the pre-existing implicit-only
+   * inference left it.
+   */
+  onApprovalResolved(taskId, payload) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    if (record.state === "Running") return;
+    if (record.state !== "AwaitApproval") {
+      console.warn(
+        `[byok/server] dropping task.approval_resolved for ${taskId}: not awaiting approval (state ${record.state})`
+      );
+      return;
+    }
+    if (payload.approvalId !== void 0 && record.pendingApprovalId !== void 0 && payload.approvalId !== record.pendingApprovalId) {
+      console.warn(
+        `[byok/server] stale task.approval_resolved for ${taskId}: reported approvalId ${payload.approvalId} does not match the currently pending ${record.pendingApprovalId}`
+      );
+      return;
+    }
+    this.applyOrFail(taskId, "Running", {});
+    const after = this.taskStore.get(taskId);
+    if (after?.state !== "Running") return;
+    const targeted = record.deviceId !== void 0 && (this.getDeviceCapabilities(record.deviceId)?.includes("approval-targeting") ?? false);
+    this.serverEvents.push({
+      kind: "task.approval_resolved",
+      taskId,
+      approvalId: payload.approvalId,
+      decision: payload.decision,
+      resolvedBy: payload.resolvedBy,
+      at: after.updatedAt,
+      targeted
+    });
+  }
+  // ---------------------------------------------------------------------
+  // transition helpers — the single place "illegal transition" is handled
+  // ---------------------------------------------------------------------
+  /**
+   * M5 (approval targeting): single low-level wrapper around
+   * `TaskStore.transition` that every ACTUAL state-changing write in this
+   * file goes through — {@link applyOrFail}'s legal-transition branch,
+   * {@link forceFailOrDrop}, and {@link resumeIfImplicitlyApproved} (the one
+   * caller that transitions WITHOUT going through `applyOrFail` at all).
+   * Two responsibilities, folded in here once rather than duplicated at
+   * each call site:
+   *
+   *   1. Clears `pendingApprovalId` whenever `record` is LEAVING
+   *      `AwaitApproval` (`record.state === 'AwaitApproval' && to !==
+   *      'AwaitApproval'`) — the id this hub last recorded for a task's
+   *      pending approval ({@link onAwaitApproval}) is meaningless the
+   *      instant that task is no longer awaiting it. Clearing it here,
+   *      centrally, is what guarantees a FUTURE `AwaitApproval` cycle for
+   *      the SAME task always starts from a clean slate instead of silently
+   *      inheriting a stale id from a previous cycle (which would make a
+   *      stale-approval check against the NEW cycle's real pending id
+   *      spuriously pass just because a leftover value happened to still be
+   *      sitting in the record).
+   *   2. Calls {@link onStateChange} — every call site already did this
+   *      immediately after its own `transition` call; folding it in here
+   *      removes the duplication and the chance of a future call site
+   *      forgetting it.
+   */
+  transitionTask(taskId, record, to, patch) {
+    const finalPatch = record.state === "AwaitApproval" && to !== "AwaitApproval" ? { ...patch, pendingApprovalId: void 0 } : patch;
+    const updated = this.taskStore.transition(taskId, to, finalPatch);
+    this.onStateChange(updated);
+    return updated;
+  }
+  /**
+   * Apply `taskId`'s state -> `target`. If that's illegal per
+   * `TASK_TRANSITIONS`, fall back to `Failed` (if reachable from the current
+   * state); this is the "illegal transition = error + task.fail path" rule.
+   */
+  applyOrFail(taskId, target, patch) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    if (canTransition(record.state, target)) {
+      this.transitionTask(taskId, record, target, patch);
+      return;
+    }
+    this.forceFailOrDrop(taskId, `illegal transition ${record.state} -> ${target}`);
+  }
+  /**
+   * M4 Phase 3 hardening (orchestrator-directed fix for the server-state-
+   * machine trace finding): a task can be resolved entirely OUT-OF-BAND, on
+   * the daemon side only (M4 Phase 3's local `approvals.resolve`
+   * control-socket path, `packages/client`) — the server never sees a wire
+   * `task.approve`/`task.reject` for it, so its own record sits in
+   * `AwaitApproval` even though the daemon already resumed and moved on.
+   *
+   * The daemon is the execution authority in this security model (the SaaS
+   * only ever *proposes* — see docs/spec.md); the daemon sending ANY further
+   * task.* traffic for a task the server still thinks is `AwaitApproval` is
+   * itself sufficient proof the approval was resolved locally, one way or
+   * another. Rather than force-failing/dropping that traffic (the pre-fix
+   * behavior — `onProgress`/`onArtifact`'s own `!== 'Running'` guard,
+   * `onComplete`'s illegal-transition fallback), this applies the exact same
+   * `AwaitApproval -> Running` edge `approveTask` already uses (a
+   * pre-existing legal `TASK_TRANSITIONS` edge, not a new one) through the
+   * normal transition path — `taskStore.transition` + `onStateChange`, same
+   * as `applyOrFail`'s own legal-transition branch — so every existing
+   * consumer of task state (§, `TaskHandle.events()`, the lease reaper's
+   * `taskActivity`) observes it exactly as it would a real wire
+   * `task.approve`. Then emits `task.approval_resolved_implicit` (a
+   * `ByokServerEvent`, NOT a wire message — see that type's own doc comment)
+   * so an embedder can distinguish this from an operator-driven approval.
+   *
+   * M4 (additive-minor, superseding this method's own former "deferred"
+   * framing): a first-class `task.approval_resolved` WIRE notification now
+   * exists (`onApprovalResolved`, below) — a daemon that supports it, talking
+   * to a server that advertised the `approval_resolved` capability flag
+   * (`version.ts`), reports a local resolution explicitly and immediately
+   * instead of leaving the server to infer it here. This method is
+   * UNTOUCHED and remains the permanent fallback for the N/N-1 cases where
+   * that explicit report never arrives (an old daemon, or an old server this
+   * daemon is talking to) — see `onApprovalResolved`'s own doc comment for
+   * the full relationship between the two paths, including why they can
+   * never both fire for the same resolution.
+   *
+   * No-op (returns `record` unchanged) for any state other than
+   * `AwaitApproval` — every other guard (terminal, pre-claim, already-
+   * Running) keeps exactly its current behavior. `onFail`/`onCancelled`
+   * never call this: `Failed`/`Cancelled` are already direct, legal edges
+   * from `AwaitApproval`, so they never hit the illegal-transition path this
+   * exists to avoid in the first place.
+   */
+  resumeIfImplicitlyApproved(record) {
+    if (record.state !== "AwaitApproval") return record;
+    const updated = this.transitionTask(record.taskId, record, "Running", {});
+    this.serverEvents.push({ kind: "task.approval_resolved_implicit", taskId: record.taskId, at: updated.updatedAt });
+    return updated;
+  }
+  /**
+   * A daemon message didn't fit the task's current state (e.g. progress
+   * while AwaitApproval). Force the task to `Failed` if that's reachable;
+   * otherwise it's already terminal (or `Offered`, which has no Failed edge)
+   * and there's nothing safe to do but log + drop.
+   */
+  forceFailOrDrop(taskId, reason) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    if (canTransition(record.state, "Failed")) {
+      this.transitionTask(taskId, record, "Failed", {
+        result: { state: "Failed", reason, retryable: false }
+      });
+      return;
+    }
+    console.warn(`[byok/server] dropping message for ${taskId} (state ${record.state}): ${reason}`);
+  }
+  onStateChange(record) {
+    this.serverEvents.push({
+      kind: "task.state",
+      taskId: record.taskId,
+      state: record.state,
+      at: record.updatedAt,
+      // M5 (claimed runtime): mirrors the snapshot's own field verbatim —
+      // see ByokServerEvent's 'task.state' variant doc comment (types.ts).
+      claimedRuntime: record.claimedRuntime
+    });
+    if (isTerminal(record.state)) {
+      this.taskActivity.delete(record.taskId);
+    }
+    const runtime = this.runtimes.get(record.taskId);
+    if (!runtime) return;
+    runtime.queue.push({ kind: "state", state: record.state, at: record.updatedAt });
+    if (isTerminal(record.state)) {
+      runtime.resolveResult(record.result ?? { state: record.state });
+      runtime.queue.close();
+    }
+  }
+  // ---------------------------------------------------------------------
+  // task-lease reaper (Decision: Failed(retryable:true) on dark-device
+  // timeout — no new task state, no new wire message)
+  // ---------------------------------------------------------------------
+  /**
+   * Task lease: a backstop for a device that goes dark mid-task and never
+   * comes back — distinct from, and layered on top of, M1's redelivery
+   * (docs/protocol.md §9), which already handles "device reconnects within
+   * the window, nothing lost." Decision (user+design): reuse the existing
+   * `Failed` terminal state and its `retryable` flag —
+   * `Failed(retryable: true, reason: 'lease-expired')` — exactly like any
+   * other `task.fail`. The embedder is expected to treat this exactly like
+   * any other retryable failure: re-dispatch as a brand-new task.
+   *
+   * Implemented as a periodic sweep (see the constructor), not a per-task
+   * timer, so a device that goes dark *after* being idle-but-connected for a
+   * while is still caught on a later tick without needing extra bookkeeping
+   * at disconnect time. `sweepLeases` reaps a task only when ALL of the
+   * following hold, checked fresh on every tick (never cached):
+   *
+   *   (a) the task is in a non-terminal *claimed* state — `Claimed`,
+   *       `Running`, or `AwaitApproval` ({@link isClaimedState}). `Offered`
+   *       is excluded: it has no owning device yet, so there's nothing to
+   *       be "dark".
+   *   (b) the owning device is dark right now ({@link deviceDarkSince}
+   *       returns a timestamp rather than `undefined`) — disconnected
+   *       outright, or (long-poll only) hasn't been seen since before the
+   *       lease window. A live WS connection is never dark from the
+   *       reaper's point of view: `heartbeat.ts` already independently
+   *       proves liveness at the transport level and flips
+   *       `connected: false` via `handleDisconnect` once it stops getting
+   *       pongs — the reaper just reads that flag rather than re-deriving
+   *       it. `deviceDarkSince` also returns *when* darkness started
+   *       ({@link ConnectionState.darkSince}, set the instant
+   *       `handleDisconnect` flips the connection dark) — that instant
+   *       feeds condition (c), below.
+   *   (c) a full `taskLeaseMs` has elapsed since the *later* of: the task's
+   *       own last inbound-activity timestamp ({@link taskActivity}, reset
+   *       in {@link dispatchToHandler} on every accepted envelope for a
+   *       known, non-terminal task — claim, started, progress, artifact,
+   *       await_approval, anything), and (b)'s dark-since instant. Taking
+   *       the *later* of the two — not the activity timestamp alone — is
+   *       what makes a device going dark start a fresh, full countdown
+   *       instead of reusing whatever (possibly already-stale) activity
+   *       timestamp the task happened to have: a task can be legitimately
+   *       idle *while connected* for longer than `taskLeaseMs` (a long turn
+   *       with no progress events, or just a quiet stretch) without being
+   *       touched — see (b) — but the instant such a task's device
+   *       disconnects, that stale activity timestamp must NOT immediately
+   *       satisfy (c) on its own, or the task would get reaped within one
+   *       sweep tick of disconnect instead of waiting the full window. That
+   *       was a real bug (a disconnect-after-long-idle reap effectively
+   *       indistinguishable from the M0 disconnect-alone-fails-the-task
+   *       behavior M1 removed, below); anchoring (c) to
+   *       `max(lastActivity, darkSince)` fixes it — idle time that elapsed
+   *       *before* the device went dark no longer counts toward the lease,
+   *       only silence *after* dark-start does.
+   *
+   * (b) and (c) are deliberately independent clocks, not one merged check.
+   * The property this most exists to protect: a *connected*, momentarily
+   * idle device mid-turn must never be reaped, no matter how long
+   * `taskLeaseMs` is — condition (b) alone blocks that regardless of (c).
+   * This is also what keeps this from reintroducing the M0 bug M1
+   * deliberately removed (see `handleDisconnect`'s own doc comment above) —
+   * M0 force-failed a task the instant its device disconnected; M1
+   * correctly stopped doing that so a task could survive a disconnect and
+   * resume via redelivery. This reaper does not revert that: disconnect
+   * ALONE still does nothing here either — (c) still has to independently
+   * hold, and per the `max(...)` above it only will once a full
+   * `taskLeaseMs` has genuinely elapsed *since the device went dark*, no
+   * matter how stale the task's own activity timestamp already was at that
+   * moment.
+   *
+   * Interaction with redelivery (§9): redelivery is what handles "the
+   * device came back within the window" — nothing to reap, normal traffic
+   * resumes. This reaper is what handles "it never came back." Idempotent
+   * claim (`onClaim`'s CAS) still protects server-side bookkeeping if a
+   * device wakes up *after* its task was already reaped and retries a stale
+   * claim/progress/etc. for it: every per-type handler's existing
+   * stale/terminal-task guard (§9) drops it as a no-op, same as any other
+   * late message for an already-terminal task — no new guard was needed for
+   * that here.
+   *
+   * Accepted residual (by design, not a bug): idempotent claim protects
+   * *server-side* state, not the device's own local side effects. A dark
+   * device that wakes up after its task has already been reaped may still
+   * be mid-way through running real local work (file writes, shell
+   * commands, whatever the runtime adapter was doing) for a task the server
+   * has since moved on from — and that the embedder may have already
+   * re-dispatched elsewhere. There is no way to remotely guarantee a
+   * truly-dark device stops running; the mitigation is entirely
+   * `taskLeaseMs` being set far larger than any realistic task duration, so
+   * this can only happen to a device that was genuinely gone for a very
+   * long time, not a normal slow turn.
+   */
+  sweepLeases() {
+    const now = Date.now();
+    for (const record of this.taskStore.list()) {
+      if (!isClaimedState(record.state) || !record.deviceId) continue;
+      const darkSince = this.deviceDarkSince(record.deviceId, now);
+      if (darkSince === void 0) continue;
+      const lastActivity = this.taskActivity.get(record.taskId) ?? Date.parse(record.updatedAt);
+      const silentSince = Math.max(lastActivity, darkSince);
+      if (now - silentSince < this.taskLeaseMs) continue;
+      this.reapTask(record.taskId);
+    }
+  }
+  /**
+   * Condition (b) above: `undefined` while `deviceId`'s connection counts as
+   * alive (never reapable, no matter how stale (c) is); otherwise the
+   * epoch-ms instant it began counting as "dark" for lease purposes.
+   * `sweepLeases` combines this with (c)'s own last-activity instant via
+   * `max(...)` so the full `taskLeaseMs` silence window is always measured
+   * from whichever of the two happened later.
+   */
+  deviceDarkSince(deviceId, nowMs) {
+    const conn = this.connections.get(deviceId);
+    if (!conn || !conn.connected) {
+      return conn?.darkSince ?? 0;
+    }
+    if (conn.ws) return void 0;
+    const lastSeenMs = Date.parse(conn.lastSeen);
+    return nowMs - lastSeenMs >= this.taskLeaseMs ? lastSeenMs : void 0;
+  }
+  /** Reap one lease-expired task through the exact same TaskStore/canTransition path — and terminal-event emission — as any other `task.fail` (see {@link applyOrFail}). */
+  reapTask(taskId) {
+    const record = this.taskStore.get(taskId);
+    if (!record || isTerminal(record.state)) return;
+    this.applyOrFail(taskId, "Failed", {
+      result: { state: "Failed", reason: "lease-expired", retryable: true }
+    });
+  }
+  // ---------------------------------------------------------------------
+  // dispatch() and the TaskHandle it returns
+  // ---------------------------------------------------------------------
+  async dispatch(input) {
+    const deviceId = input.deviceId ?? this.pickFirstConnectedDevice();
+    if (!deviceId || !this.connections.get(deviceId)?.connected) {
+      throw new Error(
+        deviceId ? `device ${deviceId} is not connected` : "no connected device to dispatch to (M0 does not queue tasks until a device connects)"
+      );
+    }
+    const taskId = generateTaskId();
+    const policy = input.policy ?? DEFAULT_POLICY;
+    const record = this.taskStore.create({
+      taskId,
+      instruction: input.instruction,
+      runtime: input.runtime,
+      policy,
+      deviceId,
+      sessionRef: input.sessionRef
+    });
+    const queue = new AsyncEventQueue();
+    let resolveResult;
+    const result = new Promise((resolve) => {
+      resolveResult = resolve;
+    });
+    this.runtimes.set(taskId, { queue, resolveResult, result });
+    queue.push({ kind: "state", state: record.state, at: record.createdAt });
+    this.serverEvents.push({ kind: "task.created", taskId, at: record.createdAt });
+    this.sendToDevice(
+      deviceId,
+      "task.offer",
+      {
+        instruction: input.instruction,
+        policy,
+        runtime: input.runtime,
+        sessionRef: input.sessionRef
+      },
+      { taskId, sessionRef: input.sessionRef }
+    );
+    return this.buildTaskHandle(taskId);
+  }
+  buildTaskHandle(taskId) {
+    const hub = this;
+    return {
+      taskId,
+      events() {
+        const runtime = hub.runtimes.get(taskId);
+        if (!runtime) throw new Error(`unknown taskId: ${taskId}`);
+        return runtime.queue.subscribe();
+      },
+      cancel(reason) {
+        return hub.cancelTask(taskId, reason);
+      },
+      approve(opts) {
+        return hub.approveTask(taskId, opts);
+      },
+      reject(reason, opts) {
+        return hub.rejectTask(taskId, reason, opts);
+      },
+      steer(text) {
+        return hub.steerTask(taskId, text);
+      },
+      result() {
+        const runtime = hub.runtimes.get(taskId);
+        if (!runtime) throw new Error(`unknown taskId: ${taskId}`);
+        return runtime.result;
+      }
+    };
+  }
+  /** Idempotent: cancelling an already-terminal task is a no-op, not an error. */
+  async cancelTask(taskId, reason) {
+    const record = this.taskStore.get(taskId);
+    if (!record) throw new Error(`unknown taskId: ${taskId}`);
+    if (isTerminal(record.state)) return;
+    this.applyOrFail(taskId, "Cancelled", { result: { state: "Cancelled", reason } });
+    if (record.deviceId) {
+      this.sendToDevice(record.deviceId, "task.cancel", { reason }, { taskId });
+    }
+  }
+  /**
+   * M4 Phase 3: made public (was private through M3) so an embedder can call
+   * it directly from its own operator-facing surface — there is no
+   * bearer-authed HTTP route for this on `http.ts`'s own app (see
+   * `UnknownTaskError`'s own doc comment for why, and
+   * `examples/basic/server.ts`'s `/api/tasks/:taskId/approve` for the
+   * intended shape of that embedder-built surface). See this file's own
+   * `UnknownTaskError`/`TaskNotAwaitingApprovalError` doc comments for why
+   * the two failure modes are now distinct typed errors rather than a
+   * single generic `Error`. Every thrown message's TEXT is byte-for-byte
+   * unchanged from M2/M3 — only the error's type changed (this is still also
+   * reachable via `TaskHandle.approve()`, unaffected).
+   */
+  /**
+   * M5 (approval targeting, docs/protocol.md §5.3): `opts.approvalId`
+   * targets a SPECIFIC pending approval rather than "whichever one is
+   * currently pending" (the pre-M5 default, unchanged when `opts` is
+   * omitted). Validated FIRST, before any state change or wire send: if
+   * `opts.approvalId` is supplied and this hub has a recorded
+   * `pendingApprovalId` for `taskId` that DIFFERS, throws
+   * {@link StaleApprovalError} — no transition, no `task.approve` sent. If
+   * this hub never recorded a `pendingApprovalId` (a legacy daemon that
+   * never reported one), the call proceeds untargeted exactly as before.
+   * The outgoing `task.approve` carries `approvalId`: the caller-supplied
+   * one if given, else this hub's own recorded one, else omitted entirely
+   * (legacy wire shape) — so the daemon can apply its own exact-match check
+   * whenever this server has an id to offer at all.
+   */
+  async approveTask(taskId, opts) {
+    const record = this.taskStore.get(taskId);
+    if (!record) throw new UnknownTaskError(taskId);
+    if (record.state !== "AwaitApproval") {
+      throw new TaskNotAwaitingApprovalError(taskId, record.state, "approve");
+    }
+    if (opts?.approvalId !== void 0 && record.pendingApprovalId !== void 0 && opts.approvalId !== record.pendingApprovalId) {
+      throw new StaleApprovalError(taskId, opts.approvalId, record.pendingApprovalId);
+    }
+    this.applyOrFail(taskId, "Running", {});
+    if (record.deviceId) {
+      const approvalId = opts?.approvalId ?? record.pendingApprovalId;
+      this.sendToDevice(record.deviceId, "task.approve", { approvalId }, { taskId });
+    }
+  }
+  /**
+   * M4 Phase 3: made public — see {@link ConnectionHub.approveTask}'s own
+   * doc comment for the full rationale (identical reasoning applies here).
+   * M5: same `opts.approvalId` targeting semantics as `approveTask` above —
+   * see that method's own doc comment.
+   */
+  async rejectTask(taskId, reason, opts) {
+    const record = this.taskStore.get(taskId);
+    if (!record) throw new UnknownTaskError(taskId);
+    if (record.state !== "AwaitApproval") {
+      throw new TaskNotAwaitingApprovalError(taskId, record.state, "reject");
+    }
+    if (opts?.approvalId !== void 0 && record.pendingApprovalId !== void 0 && opts.approvalId !== record.pendingApprovalId) {
+      throw new StaleApprovalError(taskId, opts.approvalId, record.pendingApprovalId);
+    }
+    this.applyOrFail(taskId, "Failed", {
+      result: { state: "Failed", reason: reason ?? "approval rejected", retryable: false }
+    });
+    if (record.deviceId) {
+      const approvalId = opts?.approvalId ?? record.pendingApprovalId;
+      this.sendToDevice(record.deviceId, "task.reject", { reason, approvalId }, { taskId });
+    }
+  }
+  /**
+   * S0 (GAP-002): a task-level gate, evaluated in full before any envelope is
+   * built — see {@link SteerRejectedError} for the gap this closes and why an
+   * unknown capability must refuse rather than proceed. Order matters:
+   *
+   *   1. unknown task — unchanged pre-S0 `Error` (this is not a steer-policy
+   *      decision, and `TaskHandle.steer` can only be reached with a taskId
+   *      this hub minted, so it's a programming error, not an operator one);
+   *   2. terminal (`Complete`/`Failed`/`Cancelled`) -> `task_terminal`,
+   *      checked BEFORE the `Running` check so a steer racing a terminal
+   *      transition always resolves terminal-first;
+   *   3. not `Running` (`Offered`/`Claimed`/`AwaitApproval`) ->
+   *      `task_not_running`;
+   *   4. the claim-time snapshot does not positively say `steer: true` ->
+   *      `steer_unsupported_runtime`, including when there is no snapshot at
+   *      all (fail-closed);
+   *   5. only then, the pre-existing device-liveness check and the send.
+   *
+   * Step 4 reads `TaskSnapshot.claimedRuntimeCapabilities` — the per-runtime,
+   * per-task value frozen at claim time from the claiming adapter's own
+   * `task.claim.capabilities` — and reads NO connection state whatsoever:
+   * not {@link getDeviceCapabilities}, not `ConnectionState.runtimes`, and
+   * with no fallback to either when the snapshot is absent. See
+   * {@link SteerRejectedError} for why a connection-sourced input is wrong
+   * both in scope (describes a daemon build, not this task's runtime) and in
+   * reach (absent entirely on long-poll-only daemons).
+   */
+  async steerTask(taskId, text) {
+    const record = this.taskStore.get(taskId);
+    if (!record) throw new Error(`unknown taskId: ${taskId}`);
+    if (isTerminal(record.state)) {
+      throw new SteerRejectedError(taskId, "task_terminal", record.state, record.claimedRuntime);
+    }
+    if (record.state !== "Running") {
+      throw new SteerRejectedError(taskId, "task_not_running", record.state, record.claimedRuntime);
+    }
+    if (record.claimedRuntimeCapabilities?.steer !== true) {
+      throw new SteerRejectedError(taskId, "steer_unsupported_runtime", record.state, record.claimedRuntime);
+    }
+    if (!record.deviceId || !this.connections.get(record.deviceId)?.connected) {
+      throw new Error(`device for task ${taskId} is not connected`);
+    }
+    this.sendToDevice(record.deviceId, "task.steer", { text }, { taskId });
+  }
+  pickFirstConnectedDevice() {
+    for (const [deviceId, conn] of this.connections) {
+      if (conn.connected) return deviceId;
+    }
+    return void 0;
+  }
+  // ---------------------------------------------------------------------
+  // outbound envelope delivery + per-device seq/redelivery bookkeeping (§1.2, §9)
+  // ---------------------------------------------------------------------
+  /**
+   * Build a server -> daemon envelope with a fresh per-device `seq`, retain
+   * it in that device's outbox ring buffer, and deliver it now if a live
+   * transport is available (WS send, or wake a pending long-poll).
+   *
+   * `opts`'s type mirrors `createEnvelope`'s own per-type conditional
+   * requiredness (finding F1) minus `seq` (computed fresh right here on
+   * every call, never caller-supplied) — so every one of this method's 6
+   * callers below must supply `taskId` for the 5 types that need it
+   * (everything except `conn.ack`), same as calling `createEnvelope`
+   * directly would require.
+   */
+  sendToDevice(deviceId, type, payload, opts) {
+    this.envelopesOutCount++;
+    const outbox = this.getOrCreateOutbox(deviceId);
+    const seq = outbox.nextSeq++;
+    const combinedOpts = { ...opts, seq };
+    const envelope = createEnvelope(type, payload, combinedOpts);
+    const taskId = opts.taskId;
+    const redeliverThroughTerminal = type === "task.cancel" || type === "task.reject";
+    outbox.ring.push({ seq, taskId, envelope, redeliverThroughTerminal });
+    if (outbox.ring.length > OUTBOX_RING_CAPACITY) outbox.ring.shift();
+    this.deliverToDevice(deviceId, envelope);
+    return envelope;
+  }
+  deliverToDevice(deviceId, envelope) {
+    const conn = this.connections.get(deviceId);
+    if (conn?.connected && conn.ws) {
+      conn.ws.send(encodeEnvelope(envelope));
+    }
+    this.settleLongPollWaiter(deviceId);
+  }
+  /**
+   * Retained envelopes for `deviceId` with `seq > cursor` that still belong
+   * to a non-terminal task — OR are explicitly exempted from that filter
+   * (`redeliverThroughTerminal`, N1/F4: `task.cancel`/`task.reject`) — in
+   * `seq` order. The `seq > cursor` bound is what naturally stops an
+   * exempted entry from redelivering forever: once the daemon acks it (its
+   * reported cursor advances past that `seq`), it no longer qualifies here
+   * on any future reconnect/poll.
+   */
+  collectRelevant(deviceId, cursor) {
+    const outbox = this.outboxes.get(deviceId);
+    if (!outbox) return [];
+    return outbox.ring.filter(
+      (entry) => entry.seq > cursor && entry.taskId !== void 0 && (!this.isTaskTerminal(entry.taskId) || entry.redeliverThroughTerminal)
+    ).map((entry) => entry.envelope);
+  }
+  isTaskTerminal(taskId) {
+    const record = this.taskStore.get(taskId);
+    return !record || isTerminal(record.state);
+  }
+  /** The highest `seq` assigned to `deviceId` so far — the redelivery cursor to hand back on a poll/reconnect. */
+  currentCursor(deviceId) {
+    const outbox = this.outboxes.get(deviceId);
+    return outbox ? outbox.nextSeq - 1 : 0;
+  }
+  getOrCreateOutbox(deviceId) {
+    let outbox = this.outboxes.get(deviceId);
+    if (!outbox) {
+      outbox = { nextSeq: 1, ring: [] };
+      this.outboxes.set(deviceId, outbox);
+    }
+    return outbox;
+  }
+  // ---------------------------------------------------------------------
+  // read-only accessors backing the public `machines` / `tasks` API
+  // ---------------------------------------------------------------------
+  listMachines() {
+    return this.devices.list().map(({ deviceId, deviceName }) => {
+      const conn = this.connections.get(deviceId);
+      return {
+        deviceId,
+        deviceName,
+        connected: conn?.connected ?? false,
+        lastSeen: conn?.lastSeen,
+        runtimes: conn?.runtimes
+      };
+    });
+  }
+  /**
+   * M5 (approval targeting, hello-capability plumbing): the capability flags
+   * `deviceId`'s CURRENT connection advertised in its `conn.hello` —
+   * `undefined` if this hub has no connection state for the device at all,
+   * or one that never had capabilities recorded (a pre-M5 daemon, or a
+   * device this hub only ever saw over long-poll with no prior WS hello —
+   * see `ConnectionState.capabilities`'s own doc comment). Read fresh from
+   * live connection state, mirroring `listMachines()`'s own convention; an
+   * embedder can use this to distinguish a targeting-capable device from a
+   * legacy one for its own observability/UI purposes (see `version.ts`'s
+   * `approval-targeting` flag doc comment for why this is informational
+   * only, never a correctness gate).
+   */
+  getDeviceCapabilities(deviceId) {
+    return this.connections.get(deviceId)?.capabilities;
+  }
+  getTask(taskId) {
+    return this.taskStore.get(taskId);
+  }
+  listTasks() {
+    return this.taskStore.list();
+  }
+  // ---------------------------------------------------------------------
+  // observability (M4 Phase 4, part B.1) — in-process only; see
+  // `types.ts`'s `HubStats`/`CreateByokServerOptions.healthzRoute` doc
+  // comments for why this is never exposed over HTTP by this SDK itself.
+  // ---------------------------------------------------------------------
+  /**
+   * A plain, serializable snapshot of this hub's current state, derived from
+   * existing structures (`connections`, `taskStore`) plus the small counters
+   * this file already maintains for exactly this purpose — no new
+   * bookkeeping structures beyond those counters. See {@link HubStats}
+   * (`types.ts`) for the full field-by-field contract.
+   */
+  stats() {
+    const taskCountsByState = Object.fromEntries(TASK_STATES.map((state) => [state, 0]));
+    for (const record of this.taskStore.list()) {
+      taskCountsByState[record.state]++;
+    }
+    let connectedDeviceCount = 0;
+    for (const conn of this.connections.values()) {
+      if (conn.connected) connectedDeviceCount++;
+    }
+    return {
+      connectedDeviceCount,
+      taskCountsByState,
+      envelopesIn: this.envelopesInCount,
+      envelopesOut: this.envelopesOutCount,
+      dedupDrops: this.dedupDropCount,
+      rateLimitEvents: this.rateLimitEventCount,
+      uptimeMs: Date.now() - this.startedAtMs
+    };
+  }
+};
+var IllegalTaskTransitionError = class extends Error {
+  constructor(taskId, from, to) {
+    super(`illegal task transition for ${taskId}: ${from} -> ${to}`);
+    this.taskId = taskId;
+    this.from = from;
+    this.to = to;
+    this.name = "IllegalTaskTransitionError";
+  }
+  taskId;
+  from;
+  to;
+};
+var InMemoryTaskStore = class {
+  tasks = /* @__PURE__ */ new Map();
+  create(input) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const record = {
+      taskId: input.taskId,
+      state: "Offered",
+      instruction: input.instruction,
+      runtime: input.runtime,
+      policy: input.policy,
+      deviceId: input.deviceId,
+      sessionRef: input.sessionRef,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.tasks.set(record.taskId, record);
+    return record;
+  }
+  get(taskId) {
+    return this.tasks.get(taskId);
+  }
+  list() {
+    return [...this.tasks.values()];
+  }
+  /**
+   * Apply `taskId`'s state -> `to`, merging `patch` into the record. Throws
+   * {@link IllegalTaskTransitionError} if the move isn't legal per
+   * `TASK_TRANSITIONS`, and if the task doesn't exist at all.
+   */
+  transition(taskId, to, patch = {}) {
+    const record = this.tasks.get(taskId);
+    if (!record) {
+      throw new Error(`unknown taskId: ${taskId}`);
+    }
+    if (!canTransition(record.state, to)) {
+      throw new IllegalTaskTransitionError(taskId, record.state, to);
+    }
+    const updated = {
+      ...record,
+      ...patch,
+      state: to,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.tasks.set(taskId, updated);
+    return updated;
+  }
+  /**
+   * See {@link TaskStore.setPendingApprovalId}'s own doc comment for the
+   * full rationale. State-guarded (S3 hardening): a write only applies while
+   * `taskId` is still `AwaitApproval` — mirrors `SqliteTaskStore`'s own `AND
+   * state = 'AwaitApproval'` CAS predicate (`sqlite-task-store.ts`) for
+   * symmetry between the two reference implementations, guarding against a
+   * laggard caller resurrecting a pending id after the task already left
+   * `AwaitApproval` (e.g. a queued/delayed `task.await_approval` processed
+   * after a real `approveTask`/`rejectTask` already transitioned it
+   * elsewhere). A non-matching call is a no-op: returns the record exactly
+   * as it currently stands, not the caller's requested (rejected) value.
+   */
+  setPendingApprovalId(taskId, pendingApprovalId) {
+    const record = this.tasks.get(taskId);
+    if (!record) return void 0;
+    if (record.state !== "AwaitApproval") return record;
+    const updated = { ...record, pendingApprovalId, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    this.tasks.set(taskId, updated);
+    return updated;
+  }
+};
+
+// src/heartbeat.ts
+var DEFAULT_INTERVAL_MS = 3e4;
+var DEFAULT_MAX_MISSED_PONGS = 2;
+function startHeartbeat(ws, opts = {}) {
+  const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const maxMissedPongs = opts.maxMissedPongs ?? DEFAULT_MAX_MISSED_PONGS;
+  let awaitingPong = false;
+  let missed = 0;
+  const onPong = () => {
+    awaitingPong = false;
+    missed = 0;
+  };
+  ws.on("pong", onPong);
+  const timer = setInterval(() => {
+    if (awaitingPong) {
+      missed++;
+      if (missed >= maxMissedPongs) {
+        clearInterval(timer);
+        ws.terminate();
+        return;
+      }
+    }
+    awaitingPong = true;
+    ws.ping();
+  }, intervalMs);
+  timer.unref?.();
+  return {
+    stop() {
+      clearInterval(timer);
+      ws.off("pong", onPong);
+    }
+  };
+}
+
+// src/ws-server.ts
+var WS_PATH = "/byok/ws";
+var SUPPORTED_CAPABILITIES = [...CAPABILITY_FLAGS];
+function matchesWsPath(url) {
+  return url.split("?")[0] === WS_PATH;
+}
+function rejectUpgrade(socket, code, message) {
+  const body = message;
+  const headers = [
+    `HTTP/1.1 ${code} ${message}`,
+    "Connection: close",
+    "Content-Type: text/plain",
+    `Content-Length: ${Buffer.byteLength(body)}`,
+    "",
+    ""
+  ].join("\r\n");
+  socket.once("finish", () => socket.destroy());
+  socket.end(headers + body);
+}
+function toDecodable(data) {
+  if (typeof data === "string") return data;
+  if (Array.isArray(data)) return new Uint8Array(Buffer.concat(data));
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  return data;
+}
+function attachWebSocket(server, deps) {
+  const wss = new WebSocketServer({ noServer: true });
+  server.on("upgrade", (req, socket, head) => {
+    if (!matchesWsPath(req.url ?? "")) return;
+    void (async () => {
+      const principal = await authenticateBearer(req.headers.authorization, deps);
+      if (!principal) {
+        rejectUpgrade(socket, 401, "Unauthorized");
+        return;
+      }
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        handleConnection(ws, principal, deps);
+      });
+    })();
+  });
+}
+function handleConnection(ws, principal, deps) {
+  const { deviceId } = principal;
+  let helloReceived = false;
+  let heartbeat;
+  ws.once("message", (data) => {
+    let envelope;
+    try {
+      envelope = decodeEnvelope(toDecodable(data));
+    } catch {
+      ws.close(1002, "expected conn.hello");
+      return;
+    }
+    if (envelope.type !== "conn.hello") {
+      ws.close(1002, "expected conn.hello");
+      return;
+    }
+    const payload = envelope.payload;
+    if (!payload.protocolVersions.includes(PROTOCOL_VERSION)) {
+      ws.close(1002, "unsupported protocol version");
+      return;
+    }
+    if (payload.productId !== deps.productId) {
+      ws.close(1002, "productId mismatch");
+      return;
+    }
+    if (payload.productId !== principal.productId) {
+      ws.close(1002, "productId does not match the device record");
+      return;
+    }
+    if (payload.deviceId !== deviceId) {
+      ws.close(1002, "deviceId does not match authenticated token");
+      return;
+    }
+    helloReceived = true;
+    deps.hub.registerConnection(deviceId, ws, payload.runtimes, payload.capabilities);
+    deps.hub.sendConnAck(deviceId, SUPPORTED_CAPABILITIES);
+    if (payload.cursor !== void 0) {
+      deps.hub.redeliverAfterReconnect(deviceId, payload.cursor);
+    }
+    heartbeat = startHeartbeat(ws, { intervalMs: deps.heartbeatIntervalMs });
+    ws.on("message", (msgData) => {
+      let msg;
+      try {
+        msg = decodeEnvelope(toDecodable(msgData));
+      } catch (err) {
+        console.warn(`[byok/server] dropping unparsable frame from device ${deviceId}:`, err);
+        return;
+      }
+      deps.hub.handleInbound(deviceId, msg);
+    });
+  });
+  ws.on("close", () => {
+    heartbeat?.stop();
+    if (helloReceived) {
+      deps.hub.handleDisconnect(deviceId, ws);
+    }
+  });
+}
+var SqliteUnavailableError = class extends Error {
+  constructor(cause) {
+    super(
+      "node:sqlite is unavailable in this Node.js runtime. The SQLite-backed reference stores (SqliteTaskStore/SqliteBlobStore) require Node.js 22.5+ with the built-in `node:sqlite` module (no native dependency is used or allowed here). Upgrade Node.js, or use the default InMemoryTaskStore / LocalDiskBlobStore instead."
+    );
+    this.name = "SqliteUnavailableError";
+    this.cause = cause;
+  }
+};
+var MIN_NODE_MAJOR = 22;
+var MIN_NODE_MINOR = 5;
+function isSqliteCapableNodeVersion(nodeVersion) {
+  const [majorStr, minorStr] = nodeVersion.split(".");
+  const major = Number(majorStr);
+  const minor = Number(minorStr);
+  if (!Number.isFinite(major) || !Number.isFinite(minor)) return true;
+  return major > MIN_NODE_MAJOR || major === MIN_NODE_MAJOR && minor >= MIN_NODE_MINOR;
+}
+var sqliteModule;
+function loadSqliteModule() {
+  if (sqliteModule) return sqliteModule;
+  if (!isSqliteCapableNodeVersion(process.versions.node)) {
+    throw new SqliteUnavailableError(
+      new Error(
+        `node:sqlite requires Node.js ${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}+; detected ${process.versions.node}`
+      )
+    );
+  }
+  try {
+    const require2 = createRequire(import.meta.url);
+    sqliteModule = require2("node:sqlite");
+    return sqliteModule;
+  } catch (err) {
+    throw new SqliteUnavailableError(err);
+  }
+}
+var DEFAULT_BUSY_TIMEOUT_MS = 5e3;
+var SECURE_FILE_MODE = 384;
+var SECURE_DIR_MODE = 448;
+function openSqliteDatabase(path2, options) {
+  const { DatabaseSync } = loadSqliteModule();
+  if (path2 !== ":memory:") {
+    mkdirSync(dirname(path2), { recursive: true, mode: SECURE_DIR_MODE });
+  }
+  const db = new DatabaseSync(path2, { timeout: DEFAULT_BUSY_TIMEOUT_MS, ...options });
+  if (path2 !== ":memory:") {
+    db.exec("PRAGMA journal_mode = WAL;");
+  }
+  return db;
+}
+function secureSqliteFilePermissions(dbPath) {
+  if (dbPath === ":memory:") return;
+  for (const candidate of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+    if (existsSync(candidate)) {
+      chmodSync(candidate, SECURE_FILE_MODE);
+    }
+  }
+}
+
+// src/sqlite-task-store.ts
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS tasks (
+  task_id             TEXT PRIMARY KEY,
+  state               TEXT NOT NULL,
+  instruction         TEXT NOT NULL,
+  runtime             TEXT,
+  policy_json         TEXT NOT NULL,
+  device_id           TEXT,
+  session_ref         TEXT,
+  created_at          TEXT NOT NULL,
+  updated_at          TEXT NOT NULL,
+  result_json         TEXT,
+  pending_approval_id TEXT,
+  claimed_runtime     TEXT,
+  claimed_runtime_capabilities_json TEXT
+);
+`;
+var ADDITIVE_COLUMNS = [
+  { name: "pending_approval_id", ddl: "ALTER TABLE tasks ADD COLUMN pending_approval_id TEXT" },
+  { name: "claimed_runtime", ddl: "ALTER TABLE tasks ADD COLUMN claimed_runtime TEXT" },
+  // S0 (GAP-002): the claim-time `RuntimeCapabilities` snapshot, stored as
+  // the JSON text of that closed, protocol-validated object (same idiom as
+  // `policy_json`/`result_json` above — no column-per-flag, so a future
+  // capability flag needs no further schema move). NULL means "no snapshot",
+  // which the steer gate (`hub.ts`) treats as a refusal, never as a default.
+  {
+    name: "claimed_runtime_capabilities_json",
+    ddl: "ALTER TABLE tasks ADD COLUMN claimed_runtime_capabilities_json TEXT"
+  }
+];
+function currentTaskColumns(db) {
+  return new Set(db.prepare("PRAGMA table_info(tasks)").all().map((c) => c.name));
+}
+function ensureAdditiveColumns(db) {
+  const existing = currentTaskColumns(db);
+  for (const column of ADDITIVE_COLUMNS) {
+    if (existing.has(column.name)) continue;
+    try {
+      db.exec(column.ddl);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (!/duplicate column name/i.test(message)) {
+        throw err;
+      }
+      if (!currentTaskColumns(db).has(column.name)) {
+        throw err;
+      }
+    }
+  }
+}
+function rowToRecord(row) {
+  const resultJson = row.result_json;
+  const claimedRuntimeCapabilitiesJson = row.claimed_runtime_capabilities_json;
+  return {
+    taskId: row.task_id,
+    state: row.state,
+    instruction: row.instruction,
+    runtime: row.runtime ?? void 0,
+    policy: JSON.parse(row.policy_json),
+    deviceId: row.device_id ?? void 0,
+    sessionRef: row.session_ref ?? void 0,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    result: resultJson ? JSON.parse(resultJson) : void 0,
+    pendingApprovalId: row.pending_approval_id ?? void 0,
+    claimedRuntime: row.claimed_runtime ?? void 0,
+    claimedRuntimeCapabilities: claimedRuntimeCapabilitiesJson ? JSON.parse(claimedRuntimeCapabilitiesJson) : void 0
+  };
+}
+var SqliteTaskStore = class {
+  db;
+  insertStmt;
+  updateStmt;
+  selectStmt;
+  selectAllStmt;
+  updatePendingApprovalIdStmt;
+  constructor(opts) {
+    this.db = openSqliteDatabase(opts.path);
+    this.db.exec(SCHEMA);
+    ensureAdditiveColumns(this.db);
+    secureSqliteFilePermissions(opts.path);
+    this.insertStmt = this.db.prepare(
+      `INSERT INTO tasks
+         (task_id, state, instruction, runtime, policy_json, device_id, session_ref, created_at, updated_at, result_json)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    );
+    this.updateStmt = this.db.prepare(
+      `UPDATE tasks SET
+         state = ?, instruction = ?, runtime = ?, policy_json = ?, device_id = ?,
+         session_ref = ?, created_at = ?, updated_at = ?, result_json = ?, pending_approval_id = ?,
+         claimed_runtime = ?, claimed_runtime_capabilities_json = ?
+       WHERE task_id = ? AND state = ?`
+    );
+    this.selectStmt = this.db.prepare("SELECT * FROM tasks WHERE task_id = ?");
+    this.selectAllStmt = this.db.prepare("SELECT * FROM tasks ORDER BY rowid ASC");
+    this.updatePendingApprovalIdStmt = this.db.prepare(
+      "UPDATE tasks SET pending_approval_id = ?, updated_at = ? WHERE task_id = ? AND state = 'AwaitApproval'"
+    );
+  }
+  create(input) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const record = {
+      taskId: input.taskId,
+      state: "Offered",
+      instruction: input.instruction,
+      runtime: input.runtime,
+      policy: input.policy,
+      deviceId: input.deviceId,
+      sessionRef: input.sessionRef,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.insertStmt.run(
+      record.taskId,
+      record.state,
+      record.instruction,
+      record.runtime ?? null,
+      JSON.stringify(record.policy),
+      record.deviceId ?? null,
+      record.sessionRef ?? null,
+      record.createdAt,
+      record.updatedAt,
+      record.result ? JSON.stringify(record.result) : null
+    );
+    return record;
+  }
+  get(taskId) {
+    const row = this.selectStmt.get(taskId);
+    return row ? rowToRecord(row) : void 0;
+  }
+  list() {
+    return this.selectAllStmt.all().map(rowToRecord);
+  }
+  /**
+   * Apply `taskId`'s state -> `to`, merging `patch` into the record. Throws
+   * {@link IllegalTaskTransitionError} if the move isn't legal per
+   * `TASK_TRANSITIONS`, and if the task doesn't exist at all — identical
+   * contract and error shapes to `InMemoryTaskStore.transition`.
+   *
+   * Implemented as a compare-and-set retry loop rather than a single
+   * read-validate-write, because two separate connections (two processes,
+   * or two `SqliteTaskStore` instances in this one) can both read the same
+   * current state and both validate a move against it before either writes.
+   * An unconditional `UPDATE` would let whichever commits last silently win
+   * — including an illegal terminal -> terminal transition neither
+   * validation call would have allowed with up-to-date information. Each
+   * iteration here reads the CURRENT state fresh, validates `to` against
+   * it, then writes with `WHERE state = <the state just validated>`
+   * (`updateStmt`). If zero rows changed, some other writer committed
+   * between this read and this write, so the loop re-reads and either
+   * re-validates `to` against whatever the state actually is now, or throws
+   * {@link IllegalTaskTransitionError} against it — the same outcome a
+   * caller would get if it happened to run a moment later.
+   */
+  transition(taskId, to, patch = {}) {
+    const MAX_CAS_ATTEMPTS = 100;
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+      const record = this.get(taskId);
+      if (!record) {
+        throw new Error(`unknown taskId: ${taskId}`);
+      }
+      if (!canTransition(record.state, to)) {
+        throw new IllegalTaskTransitionError(taskId, record.state, to);
+      }
+      const updated = {
+        ...record,
+        ...patch,
+        state: to,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      const { changes } = this.updateStmt.run(
+        updated.state,
+        updated.instruction,
+        updated.runtime ?? null,
+        JSON.stringify(updated.policy),
+        updated.deviceId ?? null,
+        updated.sessionRef ?? null,
+        updated.createdAt,
+        updated.updatedAt,
+        updated.result ? JSON.stringify(updated.result) : null,
+        updated.pendingApprovalId ?? null,
+        updated.claimedRuntime ?? null,
+        updated.claimedRuntimeCapabilities ? JSON.stringify(updated.claimedRuntimeCapabilities) : null,
+        updated.taskId,
+        record.state
+      );
+      if (Number(changes) > 0) {
+        return updated;
+      }
+    }
+    throw new Error(
+      `transition contention: taskId ${taskId} kept changing state under concurrent writers after ${MAX_CAS_ATTEMPTS} attempts`
+    );
+  }
+  /**
+   * See {@link TaskStore.setPendingApprovalId}'s own doc comment for the
+   * full rationale, and `updatePendingApprovalIdStmt`'s own doc comment
+   * (constructor, above) for the S3 CAS-guard rationale. The guarded
+   * statement affecting 0 rows means `taskId` is no longer `AwaitApproval`
+   * (or vanished) as of the write — a legitimate no-op, not an error: this
+   * method never throws for a state mismatch (best-effort bookkeeping, same
+   * as its unconditional pre-S3 form). Returns a FRESH read in that case
+   * rather than the caller's now-stale pre-write snapshot, so a caller sees
+   * what's actually stored.
+   */
+  setPendingApprovalId(taskId, pendingApprovalId) {
+    const record = this.get(taskId);
+    if (!record) return void 0;
+    const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const { changes } = this.updatePendingApprovalIdStmt.run(pendingApprovalId ?? null, updatedAt, taskId);
+    if (Number(changes) === 0) {
+      return this.get(taskId);
+    }
+    return { ...record, pendingApprovalId, updatedAt };
+  }
+  /**
+   * Close the underlying database connection. Not part of the `TaskStore`
+   * interface (an in-memory store has nothing to close) — call this
+   * explicitly when a store instance is done, e.g. before opening a second
+   * instance against the same file, or on process shutdown.
+   */
+  close() {
+    this.db.close();
+  }
+};
+var SCHEMA2 = `
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS blobs (
+  blob_id      TEXT PRIMARY KEY,
+  size         INTEGER NOT NULL,
+  content_type TEXT NOT NULL,
+  content_hash TEXT NOT NULL,
+  uploaded     INTEGER NOT NULL DEFAULT 0,
+  data         BLOB
+);
+`;
+var DEFAULT_URL_TTL_MS2 = 15 * 60 * 1e3;
+var SIGNING_SECRET_META_KEY = "signing_secret";
+function sha256Hex2(data) {
+  return `sha256:${createHash("sha256").update(data).digest("hex")}`;
+}
+function toBuffer(value) {
+  const view = value;
+  return Buffer.from(view.buffer, view.byteOffset, view.byteLength);
+}
+function loadOrCreateSigningSecret(db, generateCandidate = () => randomBytes(32)) {
+  const selectStmt = db.prepare("SELECT value FROM meta WHERE key = ?");
+  const existing = selectStmt.get(SIGNING_SECRET_META_KEY);
+  if (existing) return Buffer.from(existing.value, "hex");
+  const candidate = generateCandidate();
+  db.prepare("INSERT OR IGNORE INTO meta (key, value) VALUES (?, ?)").run(
+    SIGNING_SECRET_META_KEY,
+    candidate.toString("hex")
+  );
+  const persisted = selectStmt.get(SIGNING_SECRET_META_KEY);
+  if (!persisted) {
+    throw new Error("failed to initialize SQLite blob store signing secret");
+  }
+  return Buffer.from(persisted.value, "hex");
+}
+var SqliteBlobStore = class {
+  db;
+  urlTtlMs;
+  secret;
+  insertBlobStmt;
+  selectBlobStmt;
+  selectUploadedStmt;
+  writeContentStmt;
+  constructor(opts) {
+    this.db = openSqliteDatabase(opts.path);
+    this.db.exec(SCHEMA2);
+    secureSqliteFilePermissions(opts.path);
+    this.urlTtlMs = opts.urlTtlMs ?? DEFAULT_URL_TTL_MS2;
+    this.secret = opts.signingKey ?? loadOrCreateSigningSecret(this.db);
+    this.insertBlobStmt = this.db.prepare(
+      `INSERT INTO blobs (blob_id, size, content_type, content_hash, uploaded, data)
+       VALUES (?, ?, ?, ?, 0, NULL)`
+    );
+    this.selectBlobStmt = this.db.prepare(
+      "SELECT size, content_type, content_hash, uploaded, data FROM blobs WHERE blob_id = ?"
+    );
+    this.selectUploadedStmt = this.db.prepare("SELECT uploaded FROM blobs WHERE blob_id = ?");
+    this.writeContentStmt = this.db.prepare("UPDATE blobs SET data = ?, uploaded = 1 WHERE blob_id = ?");
+  }
+  async createUpload(input, requestedBlobId) {
+    const blobId = requestedBlobId ?? `blob_${randomUUID()}`;
+    const existing = this.selectBlobStmt.get(blobId);
+    if (existing !== void 0) {
+      if (existing.size !== input.size || existing.content_type !== input.contentType || existing.content_hash !== input.contentHash) {
+        throw new BlobDeclarationConflictError(blobId);
+      }
+      return { blobId, uploadUrl: this.signUrl(blobId, "put") };
+    }
+    this.insertBlobStmt.run(blobId, input.size, input.contentType, input.contentHash);
+    return { blobId, uploadUrl: this.signUrl(blobId, "put") };
+  }
+  async getDownloadUrl(blobId) {
+    const row = this.selectUploadedStmt.get(blobId);
+    if (!row?.uploaded) return void 0;
+    return this.signUrl(blobId, "get");
+  }
+  async exists(blobId) {
+    const row = this.selectUploadedStmt.get(blobId);
+    return Boolean(row?.uploaded);
+  }
+  verifySignedUrl(blobId, action, sig, exp) {
+    if (!Number.isFinite(exp) || Date.now() > exp) return false;
+    const expected = this.computeSig(blobId, action, exp);
+    const expectedBuf = Buffer.from(expected, "base64url");
+    const actualBuf = Buffer.from(sig, "base64url");
+    if (expectedBuf.length !== actualBuf.length) return false;
+    return timingSafeEqual(expectedBuf, actualBuf);
+  }
+  async writeContent(blobId, data) {
+    const row = this.selectBlobStmt.get(blobId);
+    if (!row) return { ok: false, reason: "unknown blobId" };
+    if (row.uploaded) return { ok: false, reason: "blob already uploaded" };
+    if (data.length !== row.size) {
+      return { ok: false, reason: `size mismatch: declared ${row.size}, received ${data.length}` };
+    }
+    const actualHash = sha256Hex2(data);
+    if (actualHash !== row.content_hash) {
+      return { ok: false, reason: "contentHash mismatch" };
+    }
+    this.writeContentStmt.run(data, blobId);
+    return { ok: true };
+  }
+  async readContent(blobId) {
+    const row = this.selectBlobStmt.get(blobId);
+    if (!row?.uploaded || row.data === null || row.data === void 0) return void 0;
+    return { data: toBuffer(row.data), contentType: row.content_type };
+  }
+  /** Close the underlying database connection — see `SqliteTaskStore.close`'s doc comment; same rationale. */
+  close() {
+    this.db.close();
+  }
+  computeSig(blobId, action, exp) {
+    return createHmac("sha256", this.secret).update(`${blobId}:${action}:${exp}`).digest("base64url");
+  }
+  signUrl(blobId, action) {
+    const exp = Date.now() + this.urlTtlMs;
+    const sig = this.computeSig(blobId, action, exp);
+    return `/byok/blobs/${blobId}/content?sig=${sig}&exp=${exp}`;
+  }
+};
+
+// src/index.ts
+var DEFAULT_MAX_BLOB_SIZE_BYTES = 100 * 1024 * 1024;
+var DEFAULT_LONG_POLL_HOLD_MS = 5e4;
+var DEFAULT_TASK_LEASE_MS = 30 * 6e4;
+function createByokServer(opts) {
+  const pairing = new PairingManager();
+  const devices = new DeviceRegistry();
+  const nonces = new NonceStore();
+  const tokenSigner = opts.tokenSigner ?? createHmacTokenSigner();
+  const blobStore = opts.blobStore ?? new LocalDiskBlobStore();
+  const maxBlobSizeBytes = opts.maxBlobSizeBytes ?? DEFAULT_MAX_BLOB_SIZE_BYTES;
+  const longPollHoldMs = opts.longPollHoldMs ?? DEFAULT_LONG_POLL_HOLD_MS;
+  const taskLeaseMs = opts.taskLeaseMs ?? DEFAULT_TASK_LEASE_MS;
+  const rateLimiter = new RateLimiter(opts.rateLimit);
+  const taskStore = opts.taskStore ?? new InMemoryTaskStore();
+  const hub = new ConnectionHub(taskStore, devices, taskLeaseMs, rateLimiter);
+  const hono = buildHonoApp({
+    pairing,
+    devices,
+    nonces,
+    tokenSigner,
+    blobStore,
+    maxBlobSizeBytes,
+    longPollHoldMs,
+    hub,
+    healthzRoute: opts.healthzRoute ?? false
+  });
+  return {
+    hono,
+    attachWebSocket(server) {
+      attachWebSocket(server, {
+        devices,
+        tokenSigner,
+        hub,
+        productId: opts.productId,
+        heartbeatIntervalMs: opts.heartbeatIntervalMs
+      });
+    },
+    pairing: {
+      createPairingCode: (claims) => pairing.createPairingCode(claims)
+    },
+    dispatch: (input) => hub.dispatch(input),
+    tasks: {
+      get: (taskId) => hub.getTask(taskId),
+      list: () => hub.listTasks()
+    },
+    machines: {
+      list: () => hub.listMachines()
+    },
+    events: {
+      subscribe: () => hub.subscribeServerEvents()
+    },
+    devices: {
+      revoke: (tenantId, deviceId) => devices.revoke(tenantId, deviceId)
+    },
+    stop() {
+      hub.stopLeaseReaper();
+    },
+    stats: () => hub.stats()
+  };
+}
+
+export { IllegalTaskTransitionError, InMemoryTaskStore, LocalDiskBlobStore, PairingCodeInvalidError, SqliteBlobStore, SqliteTaskStore, SqliteUnavailableError, StaleApprovalError, SteerRejectedError, createByokServer, createHmacTokenSigner };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map