@byok-sdk/server 0.7.0 → 0.8.0

package/dist/index.js

@@ -5,7 +5,7 @@ import { mkdir, writeFile, readFile } from 'fs/promises';
 import { mkdtempSync, mkdirSync, existsSync, chmodSync } from 'fs';
 import { tmpdir } from 'os';
 import path, { dirname } from 'path';
-import { CAPABILITY_FLAGS, byokBlobContentPath, canTransition, PROTOCOL_VERSION, encodeEnvelope, DAEMON_TO_SERVER_TYPES, AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY, AgentRefSchema, AgentEgressPolicySchema, DispatchSelectionSchema, RequiredToolsetsSchema, AgentContentReadPayloadSchema, createEnvelope, TASK_STATES, BYOK_PAIR_PATH, PairRequestSchema, PairResponseSchema, BYOK_CHALLENGE_PATH, ChallengeRequestSchema, BYOK_TOKEN_PATH, TokenRequestSchema, BYOK_BLOBS_PATH, CreateBlobRequestSchema, BYOK_BLOB_FINALIZE_ROUTE, BYOK_BLOB_URL_ROUTE, BYOK_BLOB_CONTENT_ROUTE, BYOK_EVENTS_PATH, BYOK_MESSAGES_PATH, MessagesSendRequestSchema, AGENT_CONTENT_ARTIFACT_READ_CAPABILITY, AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY, AGENT_CONTENT_WORKSPACE_READ_CAPABILITY, PairResponseTenantIdSchema, decodeEnvelope, BYOK_WS_PATH } from '@byok-sdk/protocol';
+import { CAPABILITY_FLAGS, byokBlobContentPath, canTransition, PROTOCOL_VERSION, encodeEnvelope, DAEMON_TO_SERVER_TYPES, AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY, AgentRefSchema, AgentEgressPolicySchema, DispatchSelectionSchema, RequiredToolsetsSchema, AGENT_EGRESS_FRESH_SESSION_CAPABILITY, AgentContentReadPayloadSchema, AgentHomeProjectionPayloadSchema, AGENT_HOME_PROJECTION_CAPABILITY, AgentHomeProjectionReadbackSchema, AgentHomeProjectionCompletionRequestSchema, createEnvelope, TASK_STATES, BYOK_PAIR_PATH, PairRequestSchema, PairResponseSchema, BYOK_CHALLENGE_PATH, ChallengeRequestSchema, BYOK_TOKEN_PATH, TokenRequestSchema, BYOK_BLOBS_PATH, CreateBlobRequestSchema, BYOK_BLOB_FINALIZE_ROUTE, BYOK_BLOB_URL_ROUTE, BYOK_BLOB_CONTENT_ROUTE, BYOK_EVENTS_PATH, BYOK_MESSAGES_PATH, MessagesSendRequestSchema, BYOK_AGENT_HOME_PROJECTION_COMPLETION_ROUTE, AGENT_CONTENT_ARTIFACT_READ_CAPABILITY, AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY, AGENT_CONTENT_WORKSPACE_READ_CAPABILITY, PairResponseTenantIdSchema, decodeEnvelope, BYOK_WS_PATH } from '@byok-sdk/protocol';
 import { Hono } from 'hono';
 import { WebSocketServer } from 'ws';
 import { createRequire } from 'module';
@@ -251,6 +251,53 @@ var LocalDiskBlobStore = class {
     return `${byokBlobContentPath(blobId)}?sig=${sig}&exp=${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();
+            }
+          }
+        };
+      }
+    };
+  }
+};
 var PAIRING_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
 function generatePairingCode(length = 8) {
   const bytes = randomBytes(length);
@@ -266,476 +313,166 @@ function generateDeviceId() {
 function generateTaskId() {
   return `task_${randomUUID()}`;
 }
-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();
+
+// 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();
   /**
-   * 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.
+   * 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.
    */
-  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() };
+  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;
   }
   /**
-   * 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.
+   * 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.
    */
-  redeemPairingCode(code) {
-    const record = this.codes.get(code);
-    if (!record) {
-      throw new PairingCodeInvalidError("unknown code");
+  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 (record.used) {
-      throw new PairingCodeInvalidError("code already used");
+    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);
+      }
     }
-    if (Date.now() > record.expiresAt) {
-      throw new PairingCodeInvalidError("code expired");
+  }
+  /**
+   * 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;
+      }
     }
-    record.used = true;
-    return record.claims;
+    if (oldestKey !== void 0) this.buckets.delete(oldestKey);
   }
 };
-function validatePairingCodeClaims(claims) {
-  if (typeof claims !== "object" || claims === null) {
-    throw new TypeError("createPairingCode requires { tenantId, productId } claims");
-  }
-  const { tenantId, productId } = claims;
-  const tenantResult = PairResponseTenantIdSchema.safeParse(tenantId);
-  if (!tenantResult.success) {
-    throw new TypeError("createPairingCode requires a valid bounded tenantId");
-  }
-  if (typeof productId !== "string" || productId.length === 0) {
-    throw new TypeError("createPairingCode requires a non-empty productId");
-  }
-  return { tenantId: tenantResult.data, 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_PATH, 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 device = deps.devices.get(claims.tenantId, deviceId);
-    if (device === void 0) {
-      throw new Error("paired device row was not persisted");
-    }
-    const { accessToken, expiresAt } = await mintAccessToken(deps.tokenSigner, {
-      deviceId: device.deviceId,
-      tenantId: device.tenantId,
-      productId: device.productId
-    });
-    const response = PairResponseSchema.parse({
-      deviceId: device.deviceId,
-      accessToken,
-      refreshHint: expiresAt,
-      tenantId: device.tenantId
-    });
-    return c.json(response, 200);
-  });
-  app.post(BYOK_CHALLENGE_PATH, 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_PATH, 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_PATH, 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_BLOB_FINALIZE_ROUTE, 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_BLOB_URL_ROUTE, 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_BLOB_CONTENT_ROUTE, 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_BLOB_CONTENT_ROUTE, 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_PATH, 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, capabilities: [...CAPABILITY_FLAGS] };
-    return c.json(response, 200);
-  });
-  app.post(BYOK_MESSAGES_PATH, 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, principal.productId);
-      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";
-}
-function sameAgentRef(expected, actual) {
-  return actual?.agentId === expected.agentId && actual.profileRevision === expected.profileRevision;
-}
-function sameAgentEgressPayload(expected, actual) {
-  return sameAgentRef(expected.agentRef, actual.agentRef) && expected.sessionRef === actual.sessionRef && expected.policyRevision === actual.policyRevision && expected.eventId === actual.eventId && expected.cursor === actual.cursor && expected.contentHash === actual.contentHash && expected.byteCount === actual.byteCount && JSON.stringify(expected.payload) === JSON.stringify(actual.payload);
-}
-function matchesContentReadReceipt(request, receipt) {
-  return request.requestId === receipt.requestId && request.surface === receipt.surface && request.actor.kind === receipt.actor.kind && request.actor.id === receipt.actor.id && sameAgentRef(request.agentRef, receipt.agentRef) && request.sessionRef === receipt.sessionRef && request.runtime === receipt.runtime && request.cwd === receipt.cwd && request.policyRevision === receipt.policyRevision && request.target === receipt.target && request.mimeType === receipt.mimeType && request.decodeAs === receipt.decodeAs;
-}
-function contentReadCapability(surface) {
-  switch (surface) {
-    case "workspace":
-      return AGENT_CONTENT_WORKSPACE_READ_CAPABILITY;
-    case "transcript":
-      return AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY;
-    case "artifact":
-      return AGENT_CONTENT_ARTIFACT_READ_CAPABILITY;
+// 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";
+}
+function sameAgentRef(expected, actual) {
+  return actual?.agentId === expected.agentId && actual.profileRevision === expected.profileRevision;
+}
+function sameAgentEgressPayload(expected, actual) {
+  return sameAgentRef(expected.agentRef, actual.agentRef) && expected.sessionRef === actual.sessionRef && expected.policyRevision === actual.policyRevision && expected.eventId === actual.eventId && expected.cursor === actual.cursor && expected.contentHash === actual.contentHash && expected.byteCount === actual.byteCount && JSON.stringify(expected.payload) === JSON.stringify(actual.payload);
+}
+function matchesContentReadReceipt(request, receipt) {
+  return request.requestId === receipt.requestId && request.surface === receipt.surface && request.actor.kind === receipt.actor.kind && request.actor.id === receipt.actor.id && sameAgentRef(request.agentRef, receipt.agentRef) && request.sessionRef === receipt.sessionRef && request.runtime === receipt.runtime && request.cwd === receipt.cwd && request.policyRevision === receipt.policyRevision && request.target === receipt.target && request.mimeType === receipt.mimeType && request.decodeAs === receipt.decodeAs;
+}
+function contentReadCapability(surface) {
+  switch (surface) {
+    case "workspace":
+      return AGENT_CONTENT_WORKSPACE_READ_CAPABILITY;
+    case "transcript":
+      return AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY;
+    case "artifact":
+      return AGENT_CONTENT_ARTIFACT_READ_CAPABILITY;
   }
 }
 var UnknownTaskError = class extends Error {
@@ -794,6 +531,14 @@ var SteerRejectedError = class extends Error {
   state;
   runtime;
 };
+var AgentHomeProjectionCompletionError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "AgentHomeProjectionCompletionError";
+  }
+  code;
+};
 var ConnectionHub = class {
   constructor(taskStore, devices, taskLeaseMs, rateLimiter = new RateLimiter()) {
     this.taskStore = taskStore;
@@ -821,6 +566,10 @@ var ConnectionHub = class {
   agentContentReadRequests = /* @__PURE__ */ new Map();
   /** Content-free explicit-read audit facts keyed by exact authenticated device/request identity. */
   agentContentReceipts = /* @__PURE__ */ new Map();
+  /** Immutable requested projection facts, keyed by authenticated device/request. */
+  agentHomeProjectionRequests = /* @__PURE__ */ new Map();
+  /** First terminal completion for each exact projection request. */
+  agentHomeProjectionCompletions = /* @__PURE__ */ new Map();
   /**
    * Per-task last-inbound-activity timestamp (epoch ms) — the task-lease
    * reaper's condition (c), see the "task-lease reaper" section below. Reset
@@ -849,1459 +598,1852 @@ var ConnectionHub = class {
    * Coalescing state only; {@link rateLimitEventCount} still counts every
    * single hit regardless of what this suppresses.
    */
-  rateLimitEventEmittedFor = /* @__PURE__ */ new Set();
+  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, configuredToolsets, clientVersion) {
+    const at = (/* @__PURE__ */ new Date()).toISOString();
+    this.connections.set(deviceId, {
+      ws,
+      connected: true,
+      lastSeen: at,
+      clientVersion,
+      runtimes,
+      capabilities,
+      configuredToolsets
+    });
+    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
+  // ---------------------------------------------------------------------
   /**
-   * 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.
+   * 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}).
    */
-  stopLeaseReaper() {
-    clearInterval(this.leaseReaperTimer);
+  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 });
+    });
   }
-  /** The top-level `events` feed returned by `createByokServer` — see {@link ByokServerEvent}. */
-  subscribeServerEvents() {
-    return this.serverEvents.subscribe();
+  /** 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,
+        configuredToolsets: conn.configuredToolsets
+      });
+      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) });
   }
   // ---------------------------------------------------------------------
-  // connection lifecycle — called from ws-server.ts / http.ts
+  // inbound envelopes from a connected daemon
   // ---------------------------------------------------------------------
   /**
-   * A daemon completed the WS handshake (`conn.hello`). Does not itself send
-   * `conn.ack` or redeliver — see {@link sendConnAck}/{@link redeliverAfterReconnect}.
+   * 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:
    *
-   * `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}.
+   * 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 arriving inbound is rejected before it's
+   *    dispatched or counted accepted. `conn.hello` is the one non-task
+   *    exception, and is accepted only from the bearer-authenticated
+   *    long-poll route with an exact device/product/protocol match.
+   * 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.
    */
-  registerConnection(deviceId, ws, runtimes, capabilities, configuredToolsets, clientVersion) {
-    const at = (/* @__PURE__ */ new Date()).toISOString();
-    this.connections.set(deviceId, {
-      ws,
-      connected: true,
-      lastSeen: at,
-      clientVersion,
-      runtimes,
-      capabilities,
-      configuredToolsets
-    });
-    this.serverEvents.push({ kind: "device.connected", deviceId, at });
-    this.settleLongPollWaiter(deviceId);
+  handleInbound(deviceId, envelope, authenticatedProductId) {
+    this.envelopesInCount++;
+    if (!this.rateLimiter.consume(deviceId)) {
+      this.handleRateLimited(deviceId);
+      return "rate_limited";
+    }
+    this.rateLimitEventEmittedFor.delete(deviceId);
+    if (envelope.type === "conn.hello") {
+      const payload = envelope.payload;
+      if (authenticatedProductId === void 0 || payload.deviceId !== deviceId || payload.productId !== authenticatedProductId || !payload.protocolVersions.includes(PROTOCOL_VERSION)) {
+        return "rejected";
+      }
+      if (this.checkAndRecordDuplicate(deviceId, envelope.id)) {
+        this.dedupDropCount++;
+        return "duplicate";
+      }
+      this.registerLongPollHello(deviceId, payload);
+      return "accepted";
+    }
+    if (!DAEMON_TO_SERVER_TYPES.includes(envelope.type)) {
+      return "rejected";
+    }
+    if (envelope.type === "agent.egress.reliable") {
+      return this.handleAgentEgressReliable(deviceId, envelope.payload);
+    }
+    if (envelope.type === "agent.content.receipt") {
+      return this.handleAgentContentReceipt(deviceId, envelope.payload);
+    }
+    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";
+  }
+  /**
+   * Store before acking. Replays must agree on every identity/cursor/hash
+   * field and receive the original receipt id; a same event id with changed
+   * facts is rejected rather than treated as an update.
+   */
+  handleAgentEgressReliable(deviceId, payload) {
+    if (!this.hasDeviceCapabilities(deviceId, [AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) {
+      return "rejected";
+    }
+    const key = this.agentEgressReceiptKey(deviceId, payload.eventId);
+    const existing = this.agentEgressReceipts.get(key);
+    if (existing !== void 0) {
+      if (!sameAgentEgressPayload(existing.payload, payload)) return "rejected";
+      this.sendAgentEgressAck(deviceId, existing);
+      this.dedupDropCount++;
+      return "duplicate";
+    }
+    const receipt = {
+      deviceId,
+      payload,
+      receiptId: crypto.randomUUID(),
+      recordedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.agentEgressReceipts.set(key, receipt);
+    this.sendAgentEgressAck(deviceId, receipt);
+    return "accepted";
+  }
+  handleAgentContentReceipt(deviceId, payload) {
+    const capability = contentReadCapability(payload.surface);
+    if (!this.hasDeviceCapabilities(deviceId, [capability, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) return "rejected";
+    if (payload.eventId !== payload.requestId) return "rejected";
+    const key = `${deviceId}\0${payload.requestId}`;
+    const request = this.agentContentReadRequests.get(key);
+    if (request === void 0 || !matchesContentReadReceipt(request, payload)) return "rejected";
+    const existing = this.agentContentReceipts.get(key);
+    if (existing !== void 0) {
+      if (JSON.stringify(existing.payload) !== JSON.stringify(payload)) return "rejected";
+      this.sendAgentContentReceiptAck(deviceId, existing);
+      this.dedupDropCount++;
+      return "duplicate";
+    }
+    const receipt = {
+      deviceId,
+      payload,
+      receiptId: payload.requestId,
+      recordedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.agentContentReceipts.set(key, receipt);
+    this.sendAgentContentReceiptAck(deviceId, receipt);
+    return "accepted";
+  }
+  sendAgentEgressAck(deviceId, receipt) {
+    this.sendToDevice(
+      deviceId,
+      "agent.egress.ack",
+      {
+        agentRef: receipt.payload.agentRef,
+        sessionRef: receipt.payload.sessionRef,
+        policyRevision: receipt.payload.policyRevision,
+        eventId: receipt.payload.eventId,
+        cursor: receipt.payload.cursor,
+        receiptId: receipt.receiptId
+      },
+      {}
+    );
   }
-  sendConnAck(deviceId, capabilities) {
+  sendAgentContentReceiptAck(deviceId, receipt) {
     this.sendToDevice(
       deviceId,
-      "conn.ack",
+      "agent.egress.ack",
       {
-        protocolVersion: PROTOCOL_VERSION,
-        capabilities,
-        serverTime: (/* @__PURE__ */ new Date()).toISOString()
+        agentRef: receipt.payload.agentRef,
+        sessionRef: receipt.payload.sessionRef,
+        policyRevision: receipt.payload.policyRevision,
+        eventId: receipt.payload.eventId,
+        cursor: receipt.payload.cursor,
+        receiptId: receipt.receiptId
       },
       {}
-      // conn.ack needs neither taskId nor sessionRef
     );
   }
+  agentEgressReceiptKey(deviceId, eventId) {
+    return `${deviceId}\0${eventId}`;
+  }
+  /** Record the authenticated long-poll equivalent of the WS opening frame. */
+  registerLongPollHello(deviceId, payload) {
+    this.takeOverAsLongPoll(deviceId);
+    const connection = this.connections.get(deviceId);
+    if (!connection) return;
+    connection.runtimes = payload.runtimes;
+    connection.capabilities = payload.capabilities;
+    connection.configuredToolsets = payload.configuredToolsets;
+    connection.lastSeen = (/* @__PURE__ */ new Date()).toISOString();
+  }
   /**
-   * 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.
+   * 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.
    */
-  redeliverAfterReconnect(deviceId, cursor) {
+  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.connected) return;
-    for (const envelope of this.collectRelevant(deviceId, cursor)) {
-      conn.ws.send(encodeEnvelope(envelope));
+    if (conn?.ws) {
+      conn.ws.close(1008, "rate limit exceeded");
     }
   }
   /**
-   * 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.
+   * 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).
    *
-   * 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).
+   * 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).
    */
-  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);
+  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(deviceId, 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());
   }
-  // ---------------------------------------------------------------------
-  // 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}).
+   * 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.deviceId !== void 0 && record.deviceId !== deviceId) {
+      console.warn(`[byok/server] dropping task.claim for ${taskId}: offered to a different device`);
+      return;
+    }
+    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
+      this.forceFailOrDrop(taskId, "task.claim AgentRef does not exactly match the offered AgentRef");
+      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.
    */
-  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) };
+  onDecline(deviceId, taskId, payload) {
+    const record = this.taskStore.get(taskId);
+    if (!record) return;
+    if (record.state !== "Offered") return;
+    if (record.deviceId !== void 0 && record.deviceId !== deviceId) {
+      console.warn(`[byok/server] dropping task.decline for ${taskId}: offered to a different device`);
+      return;
     }
-    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 });
+    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
+      this.forceFailOrDrop(taskId, "task.decline AgentRef does not exactly match the offered AgentRef");
+      return;
+    }
+    this.applyOrFail(taskId, "Failed", {
+      result: { state: "Failed", reason: payload.reason, retryable: payload.retryable }
     });
   }
-  /** 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,
-        configuredToolsets: conn.configuredToolsets
-      });
-      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;
+  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;
     }
-    if (wasFreshlyConnected) {
-      this.serverEvents.push({ kind: "device.connected", deviceId, at });
+    const runtime = this.runtimes.get(taskId);
+    if (!runtime) return;
+    for (const event of payload.events) {
+      runtime.queue.push({ kind: "agent", event });
     }
   }
-  /** 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 arriving inbound is rejected before it's
-   *    dispatched or counted accepted. `conn.hello` is the one non-task
-   *    exception, and is accepted only from the bearer-authenticated
-   *    long-poll route with an exact device/product/protocol match.
-   * 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, authenticatedProductId) {
-    this.envelopesInCount++;
-    if (!this.rateLimiter.consume(deviceId)) {
-      this.handleRateLimited(deviceId);
-      return "rate_limited";
+  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;
     }
-    this.rateLimitEventEmittedFor.delete(deviceId);
-    if (envelope.type === "conn.hello") {
-      const payload = envelope.payload;
-      if (authenticatedProductId === void 0 || payload.deviceId !== deviceId || payload.productId !== authenticatedProductId || !payload.protocolVersions.includes(PROTOCOL_VERSION)) {
-        return "rejected";
-      }
-      if (this.checkAndRecordDuplicate(deviceId, envelope.id)) {
-        this.dedupDropCount++;
-        return "duplicate";
+    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 });
       }
-      this.registerLongPollHello(deviceId, payload);
-      return "accepted";
+      return;
     }
-    if (!DAEMON_TO_SERVER_TYPES.includes(envelope.type)) {
-      return "rejected";
+    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;
+    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
+      this.forceFailOrDrop(taskId, "task.complete AgentRef does not exactly match the offered AgentRef");
+      return;
     }
-    if (envelope.type === "agent.egress.reliable") {
-      return this.handleAgentEgressReliable(deviceId, envelope.payload);
+    this.resumeIfImplicitlyApproved(record);
+    const result = {
+      state: "Complete",
+      summary: payload.summary,
+      sessionRef: payload.sessionRef,
+      artifactRefs: payload.artifactRefs,
+      // additive-minor (`task.complete.document`): projected verbatim, the
+      // same way `summary`/`artifactRefs` are. Nothing to validate or
+      // measure here — the payload only got this far because
+      // `TaskCompletePayloadSchema`'s own refinement already enforced
+      // JSON-serializability and `RESULT_DOCUMENT_MAX_BYTES` at the inbound
+      // boundary, and re-checking would make this a second authority for a
+      // rule the wire already owns. Stays `undefined` for the two cases that
+      // never carry one: a daemon with no extractor configured, and a
+      // pre-`result-document` daemon build.
+      document: payload.document
+    };
+    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;
+    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
+      this.forceFailOrDrop(taskId, "task.fail AgentRef does not exactly match the offered AgentRef");
+      return;
     }
-    if (envelope.type === "agent.content.receipt") {
-      return this.handleAgentContentReceipt(deviceId, envelope.payload);
+    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;
+    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
+      this.forceFailOrDrop(taskId, "task.cancelled AgentRef does not exactly match the offered AgentRef");
+      return;
     }
-    const taskId = envelope.task_id;
-    if (taskId === void 0) return "rejected";
+    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 && record.deviceId !== void 0 && record.deviceId !== deviceId) {
-      console.warn(`[byok/server] dropping ${envelope.type} for ${taskId}: owned by a different device`);
-      return "rejected";
+    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 (this.checkAndRecordDuplicate(deviceId, envelope.id)) {
-      this.dedupDropCount++;
-      return "duplicate";
+    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.dispatchToHandler(deviceId, taskId, envelope);
-    return "accepted";
+    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
+  // ---------------------------------------------------------------------
   /**
-   * Store before acking. Replays must agree on every identity/cursor/hash
-   * field and receive the original receipt id; a same event id with changed
-   * facts is rejected rather than treated as an update.
+   * 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.
    */
-  handleAgentEgressReliable(deviceId, payload) {
-    if (!this.hasDeviceCapabilities(deviceId, [AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) {
-      return "rejected";
-    }
-    const key = this.agentEgressReceiptKey(deviceId, payload.eventId);
-    const existing = this.agentEgressReceipts.get(key);
-    if (existing !== void 0) {
-      if (!sameAgentEgressPayload(existing.payload, payload)) return "rejected";
-      this.sendAgentEgressAck(deviceId, existing);
-      this.dedupDropCount++;
-      return "duplicate";
-    }
-    const receipt = {
-      deviceId,
-      payload,
-      receiptId: crypto.randomUUID(),
-      recordedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    this.agentEgressReceipts.set(key, receipt);
-    this.sendAgentEgressAck(deviceId, receipt);
-    return "accepted";
-  }
-  handleAgentContentReceipt(deviceId, payload) {
-    const capability = contentReadCapability(payload.surface);
-    if (!this.hasDeviceCapabilities(deviceId, [capability, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) return "rejected";
-    if (payload.eventId !== payload.requestId) return "rejected";
-    const key = `${deviceId}\0${payload.requestId}`;
-    const request = this.agentContentReadRequests.get(key);
-    if (request === void 0 || !matchesContentReadReceipt(request, payload)) return "rejected";
-    const existing = this.agentContentReceipts.get(key);
-    if (existing !== void 0) {
-      if (JSON.stringify(existing.payload) !== JSON.stringify(payload)) return "rejected";
-      this.sendAgentContentReceiptAck(deviceId, existing);
-      this.dedupDropCount++;
-      return "duplicate";
-    }
-    const receipt = {
-      deviceId,
-      payload,
-      receiptId: payload.requestId,
-      recordedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    this.agentContentReceipts.set(key, receipt);
-    this.sendAgentContentReceiptAck(deviceId, receipt);
-    return "accepted";
-  }
-  sendAgentEgressAck(deviceId, receipt) {
-    this.sendToDevice(
-      deviceId,
-      "agent.egress.ack",
-      {
-        agentRef: receipt.payload.agentRef,
-        sessionRef: receipt.payload.sessionRef,
-        policyRevision: receipt.payload.policyRevision,
-        eventId: receipt.payload.eventId,
-        cursor: receipt.payload.cursor,
-        receiptId: receipt.receiptId
-      },
-      {}
-    );
-  }
-  sendAgentContentReceiptAck(deviceId, receipt) {
-    this.sendToDevice(
-      deviceId,
-      "agent.egress.ack",
-      {
-        agentRef: receipt.payload.agentRef,
-        sessionRef: receipt.payload.sessionRef,
-        policyRevision: receipt.payload.policyRevision,
-        eventId: receipt.payload.eventId,
-        cursor: receipt.payload.cursor,
-        receiptId: receipt.receiptId
-      },
-      {}
-    );
-  }
-  agentEgressReceiptKey(deviceId, eventId) {
-    return `${deviceId}\0${eventId}`;
-  }
-  /** Record the authenticated long-poll equivalent of the WS opening frame. */
-  registerLongPollHello(deviceId, payload) {
-    this.takeOverAsLongPoll(deviceId);
-    const connection = this.connections.get(deviceId);
-    if (!connection) return;
-    connection.runtimes = payload.runtimes;
-    connection.capabilities = payload.capabilities;
-    connection.configuredToolsets = payload.configuredToolsets;
-    connection.lastSeen = (/* @__PURE__ */ new Date()).toISOString();
+  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;
   }
   /**
-   * 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.
+   * 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.
    */
-  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");
+  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}`);
   }
   /**
-   * 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.
+   * 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.
    */
-  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;
+  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;
   }
   /**
-   * 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).
+   * 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.
    */
-  dispatchToHandler(deviceId, taskId, envelope) {
+  forceFailOrDrop(taskId, reason) {
     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(deviceId, 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;
+    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}`);
   }
-  /** 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());
+  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)
+  // ---------------------------------------------------------------------
   /**
-   * 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.
+   * 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.
    *
-   * 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.
+   * 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):
    *
-   * 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`.
+   *   (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.
    *
-   * 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.
+   * (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.
    */
-  onClaim(deviceId, taskId, payload) {
-    const record = this.taskStore.get(taskId);
-    if (!record) return;
-    if (record.deviceId !== void 0 && record.deviceId !== deviceId) {
-      console.warn(`[byok/server] dropping task.claim for ${taskId}: offered to a different device`);
-      return;
-    }
-    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
-      this.forceFailOrDrop(taskId, "task.claim AgentRef does not exactly match the offered AgentRef");
-      return;
+  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);
     }
-    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.
+   * 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.
    */
-  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", {});
+  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;
   }
-  /**
-   * `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(deviceId, taskId, payload) {
+  /** 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) return;
-    if (record.state !== "Offered") return;
-    if (record.deviceId !== void 0 && record.deviceId !== deviceId) {
-      console.warn(`[byok/server] dropping task.decline for ${taskId}: offered to a different device`);
-      return;
-    }
-    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
-      this.forceFailOrDrop(taskId, "task.decline AgentRef does not exactly match the offered AgentRef");
-      return;
-    }
+    if (!record || isTerminal(record.state)) return;
     this.applyOrFail(taskId, "Failed", {
-      result: { state: "Failed", reason: payload.reason, retryable: payload.retryable }
+      result: { state: "Failed", reason: "lease-expired", retryable: true }
     });
   }
-  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 });
+  // ---------------------------------------------------------------------
+  // dispatch() and the TaskHandle it returns
+  // ---------------------------------------------------------------------
+  async dispatch(input) {
+    if (input.egressPolicy !== void 0 && input.sessionRef === void 0) {
+      throw new Error("Agent egress resume dispatch requires an exact sessionRef; use dispatchFreshAgentEgress for fresh execution");
     }
+    return this.dispatchInternal(input, false);
   }
-  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;
+  async dispatchFreshAgentEgress(input) {
+    if (Object.prototype.hasOwnProperty.call(input, "sessionRef")) {
+      throw new Error("fresh Agent egress dispatch must not carry sessionRef");
     }
-    const runtime = this.runtimes.get(taskId);
-    if (!runtime) return;
-    runtime.queue.push({ kind: "artifact", artifact: payload });
+    if (typeof input.deviceId !== "string" || input.deviceId.length === 0) {
+      throw new Error("fresh Agent egress dispatch requires an explicit deviceId");
+    }
+    if (input.agentRef === void 0 || input.egressPolicy === void 0) {
+      throw new Error("fresh Agent egress dispatch requires exact AgentRef and egress policy");
+    }
+    return this.dispatchInternal(input, true);
   }
-  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 });
+  async dispatchInternal(input, freshAgentEgress) {
+    const sessionRef = "sessionRef" in input ? input.sessionRef : void 0;
+    const agentRef = input.agentRef === void 0 ? void 0 : AgentRefSchema.parse(input.agentRef);
+    const egressPolicy = input.egressPolicy === void 0 ? void 0 : AgentEgressPolicySchema.parse(input.egressPolicy);
+    const dispatchSelection = input.dispatchSelection === void 0 ? void 0 : DispatchSelectionSchema.parse(input.dispatchSelection);
+    const requiredToolsets = input.requiredToolsets === void 0 ? void 0 : RequiredToolsetsSchema.parse(input.requiredToolsets);
+    const deviceId = input.deviceId ?? this.pickFirstConnectedDevice(requiredToolsets);
+    if (agentRef !== void 0 && input.deviceId === void 0) {
+      throw new Error("Agent-bound dispatch requires an explicit deviceId for capability admission");
+    }
+    if (egressPolicy !== void 0 && agentRef === void 0) {
+      throw new Error("Agent egress policy requires an explicit AgentRef; legacy task dispatch cannot consume it");
+    }
+    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)"
+      );
+    }
+    if (agentRef !== void 0 && !(this.getDeviceCapabilities(deviceId)?.includes("agent-home-contract") ?? false)) {
+      throw new Error(
+        `device ${deviceId} did not advertise agent-home-contract capability; refusing Agent-bound dispatch`
+      );
+    }
+    const requiredEgressCapabilities = freshAgentEgress ? [
+      AGENT_EGRESS_POLICY_CAPABILITY,
+      AGENT_EGRESS_RELIABLE_ACK_CAPABILITY,
+      AGENT_EGRESS_FRESH_SESSION_CAPABILITY
+    ] : [AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY];
+    if (egressPolicy !== void 0 && !this.hasDeviceCapabilities(deviceId, requiredEgressCapabilities)) {
+      throw new Error(
+        freshAgentEgress ? `device ${deviceId} did not advertise Agent egress policy, reliable acknowledgement, and fresh-session capabilities; refusing before enqueue` : `device ${deviceId} did not advertise Agent egress policy and reliable acknowledgement capabilities; refusing before enqueue`
+      );
+    }
+    if (dispatchSelection !== void 0 && !(this.getDeviceCapabilities(deviceId)?.includes("dispatch-selection") ?? false)) {
+      throw new Error(
+        `device ${deviceId} did not advertise dispatch-selection capability; refusing authoritative provider/model dispatch`
+      );
+    }
+    if (requiredToolsets !== void 0 && !(this.getDeviceCapabilities(deviceId)?.includes("toolset-selection") ?? false)) {
+      throw new Error(
+        `device ${deviceId} did not advertise toolset-selection capability; refusing a task whose semantics require local MCP tools`
+      );
+    }
+    if (requiredToolsets !== void 0) {
+      const configuredToolsets = this.connections.get(deviceId)?.configuredToolsets;
+      if (configuredToolsets === void 0) {
+        throw new Error(
+          `device ${deviceId} did not advertise its configured toolset inventory; refusing to guess from runtime capability`
+        );
+      }
+      const configured = new Set(configuredToolsets);
+      const missing = requiredToolsets.filter((toolsetId) => !configured.has(toolsetId));
+      if (missing.length > 0) {
+        throw new Error(
+          `device ${deviceId} is missing required MCP toolset(s): ${missing.join(", ")}`
+        );
       }
-      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;
-    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
-      this.forceFailOrDrop(taskId, "task.complete AgentRef does not exactly match the offered AgentRef");
-      return;
+    if (dispatchSelection !== void 0 && input.runtime !== void 0 && input.runtime !== dispatchSelection.runtimeId) {
+      throw new Error(
+        `dispatch runtime ${input.runtime} does not match dispatchSelection.runtimeId ${dispatchSelection.runtimeId}`
+      );
     }
-    this.resumeIfImplicitlyApproved(record);
-    const result = {
-      state: "Complete",
-      summary: payload.summary,
-      sessionRef: payload.sessionRef,
-      artifactRefs: payload.artifactRefs,
-      // additive-minor (`task.complete.document`): projected verbatim, the
-      // same way `summary`/`artifactRefs` are. Nothing to validate or
-      // measure here — the payload only got this far because
-      // `TaskCompletePayloadSchema`'s own refinement already enforced
-      // JSON-serializability and `RESULT_DOCUMENT_MAX_BYTES` at the inbound
-      // boundary, and re-checking would make this a second authority for a
-      // rule the wire already owns. Stays `undefined` for the two cases that
-      // never carry one: a daemon with no extractor configured, and a
-      // pre-`result-document` daemon build.
-      document: payload.document
+    const taskId = generateTaskId();
+    const policy = input.policy ?? DEFAULT_POLICY;
+    const runtime = dispatchSelection?.runtimeId ?? input.runtime;
+    const record = this.taskStore.create({
+      taskId,
+      instruction: input.instruction,
+      runtime,
+      policy,
+      requiredToolsets,
+      deviceId,
+      sessionRef,
+      agentRef
+    });
+    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 });
+    const commonOffer = {
+      instruction: input.instruction,
+      policy,
+      runtime,
+      dispatchSelection,
+      sessionRef
     };
-    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;
-    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
-      this.forceFailOrDrop(taskId, "task.fail AgentRef does not exactly match the offered AgentRef");
-      return;
+    if (agentRef !== void 0 && egressPolicy !== void 0 && freshAgentEgress) {
+      const freshOffer = {
+        instruction: input.instruction,
+        policy,
+        runtime,
+        dispatchSelection,
+        agentRef,
+        egressPolicy,
+        ...requiredToolsets === void 0 ? {} : { requiredToolsets }
+      };
+      this.sendToDevice(
+        deviceId,
+        "task.offer_for_agent_with_egress_fresh",
+        freshOffer,
+        { taskId }
+      );
+    } else if (agentRef !== void 0 && egressPolicy !== void 0) {
+      this.sendToDevice(
+        deviceId,
+        "task.offer_for_agent_with_egress",
+        {
+          ...commonOffer,
+          sessionRef,
+          agentRef,
+          egressPolicy,
+          ...requiredToolsets === void 0 ? {} : { requiredToolsets }
+        },
+        { taskId, sessionRef }
+      );
+    } else if (agentRef !== void 0) {
+      this.sendToDevice(
+        deviceId,
+        "task.offer_for_agent",
+        { ...commonOffer, agentRef, ...requiredToolsets === void 0 ? {} : { requiredToolsets } },
+        { taskId, sessionRef }
+      );
+    } else if (requiredToolsets === void 0) {
+      this.sendToDevice(deviceId, "task.offer", commonOffer, { taskId, sessionRef });
+    } else {
+      this.sendToDevice(
+        deviceId,
+        "task.offer_with_toolsets",
+        { ...commonOffer, requiredToolsets },
+        { taskId, sessionRef }
+      );
     }
-    const result = { state: "Failed", reason: payload.reason, retryable: payload.retryable };
-    this.applyOrFail(taskId, "Failed", { result });
+    return this.buildTaskHandle(taskId);
   }
-  /**
-   * 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;
-    if (record.agentRef && !sameAgentRef(record.agentRef, payload.agentRef)) {
-      this.forceFailOrDrop(taskId, "task.cancelled AgentRef does not exactly match the offered AgentRef");
-      return;
+  /** Capability-gated control-plane read request; no request enters the outbox on omission. */
+  async requestAgentContentRead(input) {
+    const payload = AgentContentReadPayloadSchema.parse(input.payload);
+    const deviceId = input.deviceId;
+    if (!this.connections.get(deviceId)?.connected) {
+      throw new Error(`device ${deviceId} is not connected`);
     }
-    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})`
+    const capability = contentReadCapability(payload.surface);
+    if (!this.hasDeviceCapabilities(deviceId, [capability, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) {
+      throw new Error(
+        `device ${deviceId} did not advertise ${capability} and reliable acknowledgement support; refusing Agent content read before enqueue`
       );
-      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}`
+    const key = `${deviceId}\0${payload.requestId}`;
+    const existing = this.agentContentReadRequests.get(key);
+    if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(payload)) {
+      throw new Error(`Agent content request ${payload.requestId} already exists with a different immutable body`);
+    }
+    this.agentContentReadRequests.set(key, payload);
+    this.sendToDevice(deviceId, "agent.content.read", payload, {});
+  }
+  /** Task-free exact-device projection; no task record, runtime or session is created. */
+  async enqueueAgentHomeProjection(input) {
+    const payload = AgentHomeProjectionPayloadSchema.parse(input.payload);
+    const deviceId = input.deviceId;
+    if (!this.connections.get(deviceId)?.connected) {
+      throw new Error(`device ${deviceId} is not connected`);
+    }
+    if (!this.hasDeviceCapabilities(deviceId, ["agent-home-contract", AGENT_HOME_PROJECTION_CAPABILITY])) {
+      throw new Error(
+        `device ${deviceId} did not advertise ${AGENT_HOME_PROJECTION_CAPABILITY}; refusing Agent-home projection before enqueue`
       );
-      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
+    const key = `${deviceId}\0${payload.requestId}`;
+    const existing = this.agentHomeProjectionRequests.get(key);
+    if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(payload)) {
+      throw new Error(`Agent-home projection ${payload.requestId} already exists with a different immutable body`);
+    }
+    if (existing === void 0) {
+      this.agentHomeProjectionRequests.set(key, payload);
+      this.sendToDevice(deviceId, "agent.home.projection", payload, { id: payload.requestId });
+    }
+    const readback = this.readAgentHomeProjection(deviceId, payload.requestId);
+    if (readback === void 0) throw new Error("Agent-home projection request was not retained");
+    return readback;
+  }
+  readAgentHomeProjection(deviceId, requestId) {
+    const key = `${deviceId}\0${requestId}`;
+    const completion = this.agentHomeProjectionCompletions.get(key);
+    if (completion !== void 0) return completion;
+    const desired = this.agentHomeProjectionRequests.get(key);
+    if (desired === void 0) return void 0;
+    const device = this.devices.resolveByDeviceId(deviceId);
+    if (device === void 0 || device.revoked) return void 0;
+    return AgentHomeProjectionReadbackSchema.parse({
+      tenantId: device.tenantId,
+      deviceId,
+      requestId: desired.requestId,
+      agentRef: desired.agentRef,
+      projectionHash: desired.projectionHash,
+      status: "pending"
     });
   }
-  // ---------------------------------------------------------------------
-  // 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;
+  completeAgentHomeProjection(deviceId, input) {
+    const completion = AgentHomeProjectionCompletionRequestSchema.parse(input);
+    const key = `${deviceId}\0${completion.requestId}`;
+    const desired = this.agentHomeProjectionRequests.get(key);
+    if (desired === void 0) {
+      throw new AgentHomeProjectionCompletionError("not_found", "Agent-home projection request was not found");
+    }
+    if (JSON.stringify(desired.agentRef) !== JSON.stringify(completion.agentRef) || desired.projectionHash !== completion.projectionHash) {
+      throw new AgentHomeProjectionCompletionError("invalid", "Agent-home projection completion identity mismatch");
+    }
+    const existing = this.agentHomeProjectionCompletions.get(key);
+    if (existing !== void 0) {
+      if (existing.status !== completion.outcome) {
+        throw new AgentHomeProjectionCompletionError("conflict", "Agent-home projection terminal outcome changed");
+      }
+      return existing;
+    }
+    const device = this.devices.resolveByDeviceId(deviceId);
+    if (device === void 0 || device.revoked) {
+      throw new AgentHomeProjectionCompletionError("not_found", "Agent-home projection device was not found");
+    }
+    const readback = AgentHomeProjectionReadbackSchema.parse({
+      tenantId: device.tenantId,
+      deviceId,
+      requestId: desired.requestId,
+      agentRef: desired.agentRef,
+      projectionHash: desired.projectionHash,
+      status: completion.outcome,
+      completedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    this.agentHomeProjectionCompletions.set(key, readback);
+    return readback;
   }
-  /**
-   * 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) {
+  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) return;
-    if (canTransition(record.state, target)) {
-      this.transitionTask(taskId, record, target, patch);
-      return;
+    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 });
     }
-    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.
+   * 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.
    */
-  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;
+  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 });
+    }
   }
   /**
-   * 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.
+   * 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.
    */
-  forceFailOrDrop(taskId, reason) {
+  async rejectTask(taskId, reason, opts) {
     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;
+    if (!record) throw new UnknownTaskError(taskId);
+    if (record.state !== "AwaitApproval") {
+      throw new TaskNotAwaitingApprovalError(taskId, record.state, "reject");
     }
-    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);
+    if (opts?.approvalId !== void 0 && record.pendingApprovalId !== void 0 && opts.approvalId !== record.pendingApprovalId) {
+      throw new StaleApprovalError(taskId, opts.approvalId, record.pendingApprovalId);
     }
-    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();
+    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 });
     }
   }
-  // ---------------------------------------------------------------------
-  // 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.
+   * 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:
    *
-   * 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.
+   *   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.
    *
-   * 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.
+   * 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
+   * in scope (it describes a daemon build, not this task's runtime).
    */
-  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);
+  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(requiredToolsets) {
+    for (const [deviceId, conn] of this.connections) {
+      if (!conn.connected) continue;
+      if (requiredToolsets === void 0) return deviceId;
+      if (!conn.capabilities?.includes("toolset-selection")) continue;
+      if (conn.configuredToolsets === void 0) continue;
+      const configured = new Set(conn.configuredToolsets);
+      if (requiredToolsets.every((toolsetId) => configured.has(toolsetId))) return deviceId;
+    }
+    return void 0;
   }
+  // ---------------------------------------------------------------------
+  // outbound envelope delivery + per-device seq/redelivery bookkeeping (§1.2, §9)
+  // ---------------------------------------------------------------------
   /**
-   * 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.
+   * 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.
    */
-  deviceDarkSince(deviceId, nowMs) {
+  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";
+    const redeliverWithoutTask = type === "agent.egress.ack" || type === "agent.content.read" || type === "agent.home.projection";
+    outbox.ring.push({ seq, taskId, envelope, redeliverThroughTerminal, redeliverWithoutTask });
+    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 || !conn.connected) {
-      return conn?.darkSince ?? 0;
+    if (conn?.connected && conn.ws) {
+      conn.ws.send(encodeEnvelope(envelope));
     }
-    if (conn.ws) return void 0;
-    const lastSeenMs = Date.parse(conn.lastSeen);
-    return nowMs - lastSeenMs >= this.taskLeaseMs ? lastSeenMs : void 0;
+    this.settleLongPollWaiter(deviceId);
   }
-  /** 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) {
+  /**
+   * 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 ? entry.redeliverWithoutTask === true : !this.isTaskTerminal(entry.taskId) || entry.redeliverThroughTerminal)
+    ).map((entry) => entry.envelope);
+  }
+  isTaskTerminal(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 }
-    });
+    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;
   }
   // ---------------------------------------------------------------------
-  // dispatch() and the TaskHandle it returns
+  // read-only accessors backing the public `machines` / `tasks` API
   // ---------------------------------------------------------------------
-  async dispatch(input) {
-    const agentRef = input.agentRef === void 0 ? void 0 : AgentRefSchema.parse(input.agentRef);
-    const egressPolicy = input.egressPolicy === void 0 ? void 0 : AgentEgressPolicySchema.parse(input.egressPolicy);
-    const dispatchSelection = input.dispatchSelection === void 0 ? void 0 : DispatchSelectionSchema.parse(input.dispatchSelection);
-    const requiredToolsets = input.requiredToolsets === void 0 ? void 0 : RequiredToolsetsSchema.parse(input.requiredToolsets);
-    const deviceId = input.deviceId ?? this.pickFirstConnectedDevice(requiredToolsets);
-    if (agentRef !== void 0 && input.deviceId === void 0) {
-      throw new Error("Agent-bound dispatch requires an explicit deviceId for capability admission");
-    }
-    if (egressPolicy !== void 0 && agentRef === void 0) {
-      throw new Error("Agent egress policy requires an explicit AgentRef; legacy task dispatch cannot consume it");
-    }
-    if (egressPolicy !== void 0 && input.sessionRef === void 0) {
-      throw new Error("Agent egress policy requires an exact sessionRef");
-    }
-    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)"
-      );
-    }
-    if (agentRef !== void 0 && !(this.getDeviceCapabilities(deviceId)?.includes("agent-home-contract") ?? false)) {
-      throw new Error(
-        `device ${deviceId} did not advertise agent-home-contract capability; refusing Agent-bound dispatch`
-      );
-    }
-    if (egressPolicy !== void 0 && !this.hasDeviceCapabilities(deviceId, [AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) {
-      throw new Error(
-        `device ${deviceId} did not advertise Agent egress policy and reliable acknowledgement capabilities; refusing before enqueue`
-      );
-    }
-    if (dispatchSelection !== void 0 && !(this.getDeviceCapabilities(deviceId)?.includes("dispatch-selection") ?? false)) {
-      throw new Error(
-        `device ${deviceId} did not advertise dispatch-selection capability; refusing authoritative provider/model dispatch`
-      );
-    }
-    if (requiredToolsets !== void 0 && !(this.getDeviceCapabilities(deviceId)?.includes("toolset-selection") ?? false)) {
-      throw new Error(
-        `device ${deviceId} did not advertise toolset-selection capability; refusing a task whose semantics require local MCP tools`
-      );
-    }
-    if (requiredToolsets !== void 0) {
-      const configuredToolsets = this.connections.get(deviceId)?.configuredToolsets;
-      if (configuredToolsets === void 0) {
-        throw new Error(
-          `device ${deviceId} did not advertise its configured toolset inventory; refusing to guess from runtime capability`
-        );
-      }
-      const configured = new Set(configuredToolsets);
-      const missing = requiredToolsets.filter((toolsetId) => !configured.has(toolsetId));
-      if (missing.length > 0) {
-        throw new Error(
-          `device ${deviceId} is missing required MCP toolset(s): ${missing.join(", ")}`
-        );
-      }
-    }
-    if (dispatchSelection !== void 0 && input.runtime !== void 0 && input.runtime !== dispatchSelection.runtimeId) {
-      throw new Error(
-        `dispatch runtime ${input.runtime} does not match dispatchSelection.runtimeId ${dispatchSelection.runtimeId}`
-      );
-    }
-    const taskId = generateTaskId();
-    const policy = input.policy ?? DEFAULT_POLICY;
-    const runtime = dispatchSelection?.runtimeId ?? input.runtime;
-    const record = this.taskStore.create({
-      taskId,
-      instruction: input.instruction,
-      runtime,
-      policy,
-      requiredToolsets,
-      deviceId,
-      sessionRef: input.sessionRef,
-      agentRef
-    });
-    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 });
-    const commonOffer = {
-      instruction: input.instruction,
-      policy,
-      runtime,
-      dispatchSelection,
-      sessionRef: input.sessionRef
-    };
-    if (agentRef !== void 0 && egressPolicy !== void 0) {
-      this.sendToDevice(
-        deviceId,
-        "task.offer_for_agent_with_egress",
-        {
-          ...commonOffer,
-          sessionRef: input.sessionRef,
-          agentRef,
-          egressPolicy,
-          ...requiredToolsets === void 0 ? {} : { requiredToolsets }
-        },
-        { taskId, sessionRef: input.sessionRef }
-      );
-    } else if (agentRef !== void 0) {
-      this.sendToDevice(
-        deviceId,
-        "task.offer_for_agent",
-        { ...commonOffer, agentRef, ...requiredToolsets === void 0 ? {} : { requiredToolsets } },
-        { taskId, sessionRef: input.sessionRef }
-      );
-    } else if (requiredToolsets === void 0) {
-      this.sendToDevice(deviceId, "task.offer", commonOffer, { taskId, sessionRef: input.sessionRef });
-    } else {
-      this.sendToDevice(
+  listMachines() {
+    return this.devices.list().map(({ deviceId, deviceName }) => {
+      const conn = this.connections.get(deviceId);
+      return {
         deviceId,
-        "task.offer_with_toolsets",
-        { ...commonOffer, requiredToolsets },
-        { taskId, sessionRef: input.sessionRef }
-      );
-    }
-    return this.buildTaskHandle(taskId);
+        deviceName,
+        connected: conn?.connected ?? false,
+        lastSeen: conn?.lastSeen,
+        ...conn?.clientVersion === void 0 ? {} : { clientVersion: conn.clientVersion },
+        runtimes: conn?.runtimes,
+        configuredToolsets: conn?.configuredToolsets ? [...conn.configuredToolsets] : void 0
+      };
+    });
   }
-  /** Capability-gated control-plane read request; no request enters the outbox on omission. */
-  async requestAgentContentRead(input) {
-    const payload = AgentContentReadPayloadSchema.parse(input.payload);
-    const deviceId = input.deviceId;
-    if (!this.connections.get(deviceId)?.connected) {
-      throw new Error(`device ${deviceId} is not connected`);
-    }
-    const capability = contentReadCapability(payload.surface);
-    if (!this.hasDeviceCapabilities(deviceId, [capability, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) {
-      throw new Error(
-        `device ${deviceId} did not advertise ${capability} and reliable acknowledgement support; refusing Agent content read before enqueue`
-      );
+  /**
+   * 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;
+  }
+  hasDeviceCapabilities(deviceId, required) {
+    const advertised = this.getDeviceCapabilities(deviceId);
+    return advertised !== void 0 && required.every((capability) => advertised.includes(capability));
+  }
+  getAgentEgressReceipt(deviceId, eventId) {
+    return this.agentEgressReceipts.get(this.agentEgressReceiptKey(deviceId, eventId));
+  }
+  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]++;
     }
-    const key = `${deviceId}\0${payload.requestId}`;
-    const existing = this.agentContentReadRequests.get(key);
-    if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(payload)) {
-      throw new Error(`Agent content request ${payload.requestId} already exists with a different immutable body`);
+    let connectedDeviceCount = 0;
+    for (const conn of this.connections.values()) {
+      if (conn.connected) connectedDeviceCount++;
     }
-    this.agentContentReadRequests.set(key, payload);
-    this.sendToDevice(deviceId, "agent.content.read", payload, {});
-  }
-  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;
-      }
+      connectedDeviceCount,
+      taskCountsByState,
+      envelopesIn: this.envelopesInCount,
+      envelopesOut: this.envelopesOutCount,
+      dedupDrops: this.dedupDropCount,
+      rateLimitEvents: this.rateLimitEventCount,
+      uptimeMs: Date.now() - this.startedAtMs
     };
   }
-  /** 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 });
-    }
+};
+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();
   /**
-   * 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).
+   * 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() };
+  }
   /**
-   * 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.
+   * 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.
    */
-  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");
+  redeemPairingCode(code) {
+    const record = this.codes.get(code);
+    if (!record) {
+      throw new PairingCodeInvalidError("unknown code");
     }
-    if (opts?.approvalId !== void 0 && record.pendingApprovalId !== void 0 && opts.approvalId !== record.pendingApprovalId) {
-      throw new StaleApprovalError(taskId, opts.approvalId, record.pendingApprovalId);
+    if (record.used) {
+      throw new PairingCodeInvalidError("code already used");
     }
-    this.applyOrFail(taskId, "Running", {});
-    if (record.deviceId) {
-      const approvalId = opts?.approvalId ?? record.pendingApprovalId;
-      this.sendToDevice(record.deviceId, "task.approve", { approvalId }, { taskId });
+    if (Date.now() > record.expiresAt) {
+      throw new PairingCodeInvalidError("code expired");
     }
+    record.used = true;
+    return record.claims;
   }
-  /**
-   * 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");
+};
+function validatePairingCodeClaims(claims) {
+  if (typeof claims !== "object" || claims === null) {
+    throw new TypeError("createPairingCode requires { tenantId, productId } claims");
+  }
+  const { tenantId, productId } = claims;
+  const tenantResult = PairResponseTenantIdSchema.safeParse(tenantId);
+  if (!tenantResult.success) {
+    throw new TypeError("createPairingCode requires a valid bounded tenantId");
+  }
+  if (typeof productId !== "string" || productId.length === 0) {
+    throw new TypeError("createPairingCode requires a non-empty productId");
+  }
+  return { tenantId: tenantResult.data, 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_PATH, async (c) => {
+    const parsed = PairRequestSchema.safeParse(await readJsonBody(c));
+    if (!parsed.success) {
+      return c.json({ error: "pairingCode, deviceName, and devicePublicKey are required strings" }, 400);
     }
-    if (opts?.approvalId !== void 0 && record.pendingApprovalId !== void 0 && opts.approvalId !== record.pendingApprovalId) {
-      throw new StaleApprovalError(taskId, opts.approvalId, record.pendingApprovalId);
+    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;
     }
-    this.applyOrFail(taskId, "Failed", {
-      result: { state: "Failed", reason: reason ?? "approval rejected", retryable: false }
+    const deviceId = generateDeviceId();
+    deps.devices.register({
+      tenantId: claims.tenantId,
+      productId: claims.productId,
+      deviceId,
+      deviceName,
+      devicePublicKey
     });
-    if (record.deviceId) {
-      const approvalId = opts?.approvalId ?? record.pendingApprovalId;
-      this.sendToDevice(record.deviceId, "task.reject", { reason, approvalId }, { taskId });
+    const device = deps.devices.get(claims.tenantId, deviceId);
+    if (device === void 0) {
+      throw new Error("paired device row was not persisted");
     }
-  }
-  /**
-   * 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
-   * in scope (it describes a daemon build, not this task's runtime).
-   */
-  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);
+    const { accessToken, expiresAt } = await mintAccessToken(deps.tokenSigner, {
+      deviceId: device.deviceId,
+      tenantId: device.tenantId,
+      productId: device.productId
+    });
+    const response = PairResponseSchema.parse({
+      deviceId: device.deviceId,
+      accessToken,
+      refreshHint: expiresAt,
+      tenantId: device.tenantId
+    });
+    return c.json(response, 200);
+  });
+  app.post(BYOK_CHALLENGE_PATH, 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_PATH, 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_PATH, 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;
     }
-    if (record.state !== "Running") {
-      throw new SteerRejectedError(taskId, "task_not_running", record.state, record.claimedRuntime);
+  });
+  app.post(BYOK_BLOB_FINALIZE_ROUTE, 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);
     }
-    if (record.claimedRuntimeCapabilities?.steer !== true) {
-      throw new SteerRejectedError(taskId, "steer_unsupported_runtime", record.state, record.claimedRuntime);
+    const blobId = c.req.param("id");
+    if (reservationBlobId(principal.tenantId, reservationId) !== blobId) {
+      return c.json({ error: "storage_integrity_mismatch" }, 422);
     }
-    if (!record.deviceId || !this.connections.get(record.deviceId)?.connected) {
-      throw new Error(`device for task ${taskId} is not connected`);
+    if (!await deps.blobStore.exists(blobId)) {
+      return c.json({ error: "storage_reservation_not_found" }, 404);
     }
-    this.sendToDevice(record.deviceId, "task.steer", { text }, { taskId });
-  }
-  pickFirstConnectedDevice(requiredToolsets) {
-    for (const [deviceId, conn] of this.connections) {
-      if (!conn.connected) continue;
-      if (requiredToolsets === void 0) return deviceId;
-      if (!conn.capabilities?.includes("toolset-selection")) continue;
-      if (conn.configuredToolsets === void 0) continue;
-      const configured = new Set(conn.configuredToolsets);
-      if (requiredToolsets.every((toolsetId) => configured.has(toolsetId))) return deviceId;
+    return c.body(null, 204);
+  });
+  app.get(BYOK_BLOB_URL_ROUTE, 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_BLOB_CONTENT_ROUTE, 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);
     }
-    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";
-    const redeliverWithoutTask = type === "agent.egress.ack" || type === "agent.content.read";
-    outbox.ring.push({ seq, taskId, envelope, redeliverThroughTerminal, redeliverWithoutTask });
-    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));
+    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_BLOB_CONTENT_ROUTE, 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);
     }
-    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 ? entry.redeliverWithoutTask === true : !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);
+    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_PATH, 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;
     }
-    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,
-        ...conn?.clientVersion === void 0 ? {} : { clientVersion: conn.clientVersion },
-        runtimes: conn?.runtimes,
-        configuredToolsets: conn?.configuredToolsets ? [...conn.configuredToolsets] : void 0
-      };
-    });
-  }
-  /**
-   * 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;
-  }
-  hasDeviceCapabilities(deviceId, required) {
-    const advertised = this.getDeviceCapabilities(deviceId);
-    return advertised !== void 0 && required.every((capability) => advertised.includes(capability));
-  }
-  getAgentEgressReceipt(deviceId, eventId) {
-    return this.agentEgressReceipts.get(this.agentEgressReceiptKey(deviceId, eventId));
-  }
-  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]++;
+    const result = await deps.hub.pollEvents(principal.deviceId, cursor, deps.longPollHoldMs);
+    const response = { ...result, capabilities: [...CAPABILITY_FLAGS] };
+    return c.json(response, 200);
+  });
+  app.post(BYOK_MESSAGES_PATH, 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, principal.productId);
+      if (result === "rate_limited") {
+        return c.json({ error: "rate limit exceeded" }, 429);
+      }
+      if (result === "rejected") rejected++;
+      else accepted++;
     }
-    let connectedDeviceCount = 0;
-    for (const conn of this.connections.values()) {
-      if (conn.connected) connectedDeviceCount++;
+    const response = rejected > 0 ? { accepted, rejected } : { accepted };
+    return c.json(response, 200);
+  });
+  app.put(BYOK_AGENT_HOME_PROJECTION_COMPLETION_ROUTE, async (c) => {
+    const principal = await authenticateBearer(c.req.header("authorization"), deps);
+    if (!principal) return c.json({ error: "unauthorized" }, 401);
+    const parsed = AgentHomeProjectionCompletionRequestSchema.safeParse(await readJsonBody(c));
+    if (!parsed.success || parsed.data.requestId !== c.req.param("requestId")) {
+      return c.json({ error: "invalid Agent-home projection completion" }, 422);
     }
-    return {
-      connectedDeviceCount,
-      taskCountsByState,
-      envelopesIn: this.envelopesInCount,
-      envelopesOut: this.envelopesOutCount,
-      dedupDrops: this.dedupDropCount,
-      rateLimitEvents: this.rateLimitEventCount,
-      uptimeMs: Date.now() - this.startedAtMs
-    };
-  }
-};
+    try {
+      return c.json(deps.hub.completeAgentHomeProjection(principal.deviceId, parsed.data), 200);
+    } catch (error) {
+      if (error instanceof AgentHomeProjectionCompletionError) {
+        if (error.code === "not_found") return c.json({ error: error.message }, 404);
+        if (error.code === "conflict") return c.json({ error: error.message }, 409);
+        return c.json({ error: error.message }, 422);
+      }
+      throw error;
+    }
+  });
+  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 };
+}
 var IllegalTaskTransitionError = class extends Error {
   constructor(taskId, from, to) {
     super(`illegal task transition for ${taskId}: ${from} -> ${to}`);
@@ -3035,7 +3177,10 @@ function createByokServer(opts) {
       createPairingCode: (claims) => pairing.createPairingCode(claims)
     },
     dispatch: (input) => hub.dispatch(input),
+    dispatchFreshAgentEgress: (input) => hub.dispatchFreshAgentEgress(input),
     requestAgentContentRead: (input) => hub.requestAgentContentRead(input),
+    enqueueAgentHomeProjection: (input) => hub.enqueueAgentHomeProjection(input),
+    readAgentHomeProjection: (deviceId, requestId) => hub.readAgentHomeProjection(deviceId, requestId),
     tasks: {
       get: (taskId) => hub.getTask(taskId),
       list: () => hub.listTasks()
@@ -3059,6 +3204,6 @@ function createByokServer(opts) {
   };
 }
 
-export { IllegalTaskTransitionError, InMemoryTaskStore, LocalDiskBlobStore, PairingCodeInvalidError, SqliteBlobStore, SqliteTaskStore, SqliteUnavailableError, StaleApprovalError, SteerRejectedError, createByokServer, createHmacTokenSigner };
+export { AgentHomeProjectionCompletionError, IllegalTaskTransitionError, InMemoryTaskStore, LocalDiskBlobStore, PairingCodeInvalidError, SqliteBlobStore, SqliteTaskStore, SqliteUnavailableError, StaleApprovalError, SteerRejectedError, createByokServer, createHmacTokenSigner };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map