@spotpatch/dev-server 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -34,6 +34,7 @@ __export(index_exports, {
   DEFAULT_OPTIONS: () => DEFAULT_OPTIONS,
   applyIntegrationPlan: () => applyIntegrationPlan,
   createAgentJobManager: () => createAgentJobManager,
+  createExternalHandoffService: () => createExternalHandoffService,
   createIntegrationFileChange: () => createIntegrationFileChange,
   createRuntimeAiConfig: () => createRuntimeAiConfig,
   createRuntimeDataFlowConfig: () => createRuntimeDataFlowConfig,
@@ -521,6 +522,1064 @@ function createAgentJobManager(options) {
   });
 }
 
+// src/external-handoff/service.ts
+var import_shared7 = require("@spotpatch/shared");
+var import_external_agent_node3 = require("@spotpatch/shared/external-agent-node");
+
+// src/external-handoff/active-registry.ts
+var import_node_crypto2 = require("crypto");
+var import_shared2 = require("@spotpatch/shared");
+
+// src/external-handoff/clock.ts
+var import_node_perf_hooks = require("perf_hooks");
+var SYSTEM_EXTERNAL_HANDOFF_CLOCK = Object.freeze({
+  monotonicNow: () => import_node_perf_hooks.performance.now(),
+  wallNow: () => Date.now()
+});
+
+// src/external-handoff/active-registry.ts
+var ALLOWED_TRANSITIONS = Object.freeze({
+  queued: ["dispatching", "failed"],
+  dispatching: ["dispatched", "working", "failed", "delivery-unknown"],
+  dispatched: ["working", "failed", "delivery-unknown"],
+  working: ["completed", "failed", "delivery-unknown"],
+  completed: [],
+  failed: [],
+  "delivery-unknown": []
+});
+var TERMINAL_PHASES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "delivery-unknown"
+]);
+function defaultRandomId() {
+  return (0, import_node_crypto2.randomBytes)(32).toString("base64url");
+}
+function requirePresent(value) {
+  if (value === null) throw new import_shared2.SpotPatchError(import_shared2.ERROR_CODES.INTERNAL_ERROR);
+  return value;
+}
+function createActiveAdapterRegistry(options = {}) {
+  const clock = options.clock ?? SYSTEM_EXTERNAL_HANDOFF_CLOCK;
+  const randomId = options.randomId ?? defaultRandomId;
+  let blocked;
+  let closed = false;
+  let dispatch;
+  let lastReleasedToken;
+  let lease;
+  const nowIso = () => new Date(clock.wallNow()).toISOString();
+  const requireOpen = () => {
+    if (closed) throw new import_shared2.SpotPatchError(import_shared2.ERROR_CODES.SESSION_CLOSED);
+  };
+  const dispatchSummary = () => dispatch === void 0 ? null : Object.freeze({
+    adapterKind: dispatch.adapterKind,
+    revision: dispatch.revision,
+    phase: dispatch.phase,
+    updatedAt: dispatch.updatedAt
+  });
+  const activeSummary = () => {
+    if (blocked !== void 0) {
+      return Object.freeze({
+        kind: blocked.adapterKind,
+        state: "blocked",
+        canDispatch: false,
+        connectedAt: blocked.connectedAt,
+        updatedAt: blocked.updatedAt
+      });
+    }
+    if (lease === void 0) return null;
+    const busy = dispatch !== void 0 && !TERMINAL_PHASES.has(dispatch.phase);
+    return Object.freeze({
+      kind: lease.adapterKind,
+      state: busy ? "busy" : "ready",
+      canDispatch: !busy,
+      connectedAt: lease.connectedAt,
+      updatedAt: lease.updatedAt
+    });
+  };
+  const state = (cursor) => Object.freeze({
+    activeAdapter: activeSummary(),
+    dispatch: cursor === void 0 || dispatch?.cursor === cursor ? dispatchSummary() : null
+  });
+  const enterUnknown = (activeLease) => {
+    if (dispatch === void 0) return;
+    const updatedAt = nowIso();
+    dispatch.phase = "delivery-unknown";
+    dispatch.updatedAt = updatedAt;
+    blocked = Object.freeze({
+      adapterKind: activeLease.adapterKind,
+      connectedAt: activeLease.connectedAt,
+      updatedAt
+    });
+  };
+  const endLease = (activeLease) => {
+    if (dispatch?.phase === "queued") {
+      dispatch.phase = "failed";
+      dispatch.updatedAt = nowIso();
+    } else if (dispatch?.phase === "dispatching" || dispatch?.phase === "dispatched" || dispatch?.phase === "working") {
+      enterUnknown(activeLease);
+    }
+    lastReleasedToken = activeLease.token;
+    lease = void 0;
+  };
+  const sweep = () => {
+    if (lease === void 0) return;
+    const monotonicNow = clock.monotonicNow();
+    if (monotonicNow >= lease.expiresAtMonotonic || dispatch !== void 0 && !TERMINAL_PHASES.has(dispatch.phase) && monotonicNow >= dispatch.deadlineMonotonic) {
+      endLease(lease);
+    }
+  };
+  const assertPublishable = () => {
+    requireOpen();
+    sweep();
+    if (blocked !== void 0 || lease !== void 0 && dispatch !== void 0 && !TERMINAL_PHASES.has(dispatch.phase)) {
+      throw new import_shared2.SpotPatchError(import_shared2.ERROR_CODES.EXTERNAL_AGENT_BUSY);
+    }
+  };
+  const requireLease = (leaseToken) => {
+    requireOpen();
+    sweep();
+    if (lease?.token !== leaseToken) {
+      throw new import_shared2.SpotPatchError(import_shared2.ERROR_CODES.ACTIVE_ADAPTER_LEASE_INVALID);
+    }
+    return lease;
+  };
+  return Object.freeze({
+    assertPublishable,
+    claim(adapterKind, connectorInstanceId, baselineCursor) {
+      requireOpen();
+      sweep();
+      if (blocked !== void 0) {
+        throw new import_shared2.SpotPatchError(import_shared2.ERROR_CODES.EXTERNAL_AGENT_BUSY);
+      }
+      if (lease !== void 0) {
+        if (lease.adapterKind === adapterKind && lease.connectorInstanceId === connectorInstanceId) {
+          lease.expiresAtMonotonic = clock.monotonicNow() + import_shared2.EXTERNAL_HANDOFF_LIMITS.activeLeaseDurationMs;
+          lease.updatedAt = nowIso();
+          return Object.freeze({
+            leaseToken: lease.token,
+            heartbeatIntervalMs: import_shared2.EXTERNAL_HANDOFF_LIMITS.activeHeartbeatIntervalMs,
+            baselineCursor: lease.baselineCursor,
+            activeAdapter: requirePresent(activeSummary())
+          });
+        }
+        throw new import_shared2.SpotPatchError(import_shared2.ERROR_CODES.ACTIVE_ADAPTER_CONFLICT);
+      }
+      const timestamp = nowIso();
+      lease = {
+        adapterKind,
+        baselineCursor,
+        connectedAt: timestamp,
+        connectorInstanceId,
+        token: randomId(),
+        expiresAtMonotonic: clock.monotonicNow() + import_shared2.EXTERNAL_HANDOFF_LIMITS.activeLeaseDurationMs,
+        updatedAt: timestamp
+      };
+      lastReleasedToken = void 0;
+      return Object.freeze({
+        leaseToken: lease.token,
+        heartbeatIntervalMs: import_shared2.EXTERNAL_HANDOFF_LIMITS.activeHeartbeatIntervalMs,
+        baselineCursor,
+        activeAdapter: requirePresent(activeSummary())
+      });
+    },
+    heartbeat(leaseToken) {
+      const activeLease = requireLease(leaseToken);
+      activeLease.expiresAtMonotonic = clock.monotonicNow() + import_shared2.EXTERNAL_HANDOFF_LIMITS.activeLeaseDurationMs;
+      activeLease.updatedAt = nowIso();
+      return state();
+    },
+    report(leaseToken, cursor, phase) {
+      const activeLease = requireLease(leaseToken);
+      if (dispatch?.cursor !== cursor || dispatch.adapterKind !== activeLease.adapterKind) {
+        throw new import_shared2.SpotPatchError(import_shared2.ERROR_CODES.ACTIVE_DISPATCH_INVALID);
+      }
+      if (dispatch.phase === phase) return state(cursor);
+      const allowed = ALLOWED_TRANSITIONS[dispatch.phase];
+      if (!allowed.includes(phase)) {
+        throw new import_shared2.SpotPatchError(import_shared2.ERROR_CODES.ACTIVE_DISPATCH_INVALID);
+      }
+      const updatedAt = nowIso();
+      dispatch.phase = phase;
+      dispatch.updatedAt = updatedAt;
+      activeLease.updatedAt = updatedAt;
+      if (phase === "delivery-unknown") {
+        blocked = Object.freeze({
+          adapterKind: activeLease.adapterKind,
+          connectedAt: activeLease.connectedAt,
+          updatedAt
+        });
+        lastReleasedToken = activeLease.token;
+        lease = void 0;
+      }
+      return state(cursor);
+    },
+    release(leaseToken) {
+      requireOpen();
+      sweep();
+      if (lease === void 0 && lastReleasedToken === leaseToken) return state();
+      const activeLease = lease;
+      if (activeLease?.token !== leaseToken) {
+        throw new import_shared2.SpotPatchError(import_shared2.ERROR_CODES.ACTIVE_ADAPTER_LEASE_INVALID);
+      }
+      endLease(activeLease);
+      return state();
+    },
+    reserve(cursor, revision) {
+      assertPublishable();
+      if (lease === void 0) return Object.freeze({ mode: "inbox" });
+      const updatedAt = nowIso();
+      dispatch = {
+        adapterKind: lease.adapterKind,
+        cursor,
+        deadlineMonotonic: clock.monotonicNow() + import_shared2.EXTERNAL_HANDOFF_LIMITS.activeDispatchTimeoutMs,
+        revision,
+        phase: "queued",
+        updatedAt
+      };
+      lease.updatedAt = updatedAt;
+      return Object.freeze({
+        mode: "active",
+        adapter: requirePresent(activeSummary()),
+        dispatch: requirePresent(dispatchSummary())
+      });
+    },
+    resolveDelivery(cursor) {
+      requireOpen();
+      sweep();
+      const activeDispatch = dispatch;
+      if (blocked === void 0 || activeDispatch?.cursor !== cursor || activeDispatch.phase !== "delivery-unknown") {
+        throw new import_shared2.SpotPatchError(import_shared2.ERROR_CODES.ACTIVE_DISPATCH_INVALID);
+      }
+      blocked = void 0;
+      return state(cursor);
+    },
+    snapshot(cursor) {
+      requireOpen();
+      sweep();
+      return state(cursor);
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      blocked = void 0;
+      dispatch = void 0;
+      lease = void 0;
+      lastReleasedToken = void 0;
+    }
+  });
+}
+
+// src/external-handoff/broker.ts
+var import_node_crypto3 = require("crypto");
+var import_node_http = require("http");
+var import_shared4 = require("@spotpatch/shared");
+var import_external_agent_node = require("@spotpatch/shared/external-agent-node");
+
+// src/server/request-body.ts
+var import_shared3 = require("@spotpatch/shared");
+
+// src/server/constants.ts
+var MAX_REQUEST_BODY_BYTES = 32 * 1024;
+var MAX_AGENT_REQUEST_BODY_BYTES = 256 * 1024;
+var MAX_SOURCE_FILE_BYTES = 1024 * 1024;
+
+// src/server/request-body.ts
+function isJsonContentType(value) {
+  return value?.split(";", 1)[0]?.trim().toLowerCase() === "application/json";
+}
+async function readJsonRequestBody(request, maximumBytes = MAX_REQUEST_BODY_BYTES) {
+  if (!isJsonContentType(request.headers["content-type"])) {
+    throw new import_shared3.SpotPatchError(import_shared3.ERROR_CODES.INVALID_REQUEST);
+  }
+  const declaredLength = Number(request.headers["content-length"]);
+  if (Number.isFinite(declaredLength) && declaredLength > maximumBytes) {
+    throw new import_shared3.SpotPatchError(import_shared3.ERROR_CODES.INVALID_REQUEST);
+  }
+  const chunks = [];
+  let byteLength = 0;
+  let exceededLimit = false;
+  for await (const rawChunk of request) {
+    const chunk = rawChunk;
+    if (typeof chunk !== "string" && !(chunk instanceof Uint8Array)) {
+      throw new import_shared3.SpotPatchError(import_shared3.ERROR_CODES.INVALID_REQUEST);
+    }
+    const buffer = Buffer.from(chunk);
+    byteLength += buffer.byteLength;
+    if (byteLength > maximumBytes) {
+      exceededLimit = true;
+      continue;
+    }
+    chunks.push(buffer);
+  }
+  if (exceededLimit || byteLength === 0) {
+    throw new import_shared3.SpotPatchError(import_shared3.ERROR_CODES.INVALID_REQUEST);
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch (error) {
+    throw new import_shared3.SpotPatchError(import_shared3.ERROR_CODES.INVALID_REQUEST, void 0, {
+      cause: error
+    });
+  }
+}
+
+// src/external-handoff/broker.ts
+function singleHeader(request, name) {
+  const value = request.headers[name.toLowerCase()];
+  return Array.isArray(value) ? void 0 : value;
+}
+function tokensMatch(actual, expected) {
+  if (actual === void 0) return false;
+  const actualBytes = Buffer.from(actual);
+  const expectedBytes = Buffer.from(expected);
+  return actualBytes.byteLength === expectedBytes.byteLength && (0, import_node_crypto3.timingSafeEqual)(actualBytes, expectedBytes);
+}
+function writeJson(response, status, payload) {
+  response.statusCode = status;
+  response.setHeader("Cache-Control", "no-store");
+  response.setHeader("Connection", "close");
+  response.setHeader("Content-Type", "application/json; charset=utf-8");
+  response.setHeader("X-Content-Type-Options", "nosniff");
+  response.end(JSON.stringify(payload));
+}
+function statusForError(code) {
+  if (code === import_shared4.ERROR_CODES.BRIDGE_UNAUTHORIZED) return 401;
+  if (code === import_shared4.ERROR_CODES.HANDOFF_NOT_FOUND) return 404;
+  if (code === import_shared4.ERROR_CODES.HANDOFF_EXPIRED || code === import_shared4.ERROR_CODES.SESSION_CLOSED) {
+    return 410;
+  }
+  if (code === import_shared4.ERROR_CODES.BRIDGE_BUSY) return 429;
+  if (code === import_shared4.ERROR_CODES.ACTIVE_ADAPTER_LEASE_INVALID) return 401;
+  if (code === import_shared4.ERROR_CODES.HANDOFF_RESPONSE_TOO_LARGE) return 413;
+  if (code === import_shared4.ERROR_CODES.HANDOFF_CURSOR_INVALID || code === import_shared4.ERROR_CODES.BRIDGE_PROTOCOL_MISMATCH || code === import_shared4.ERROR_CODES.EXTERNAL_AGENT_BUSY || code === import_shared4.ERROR_CODES.ACTIVE_ADAPTER_CONFLICT || code === import_shared4.ERROR_CODES.ACTIVE_DISPATCH_INVALID) {
+    return 409;
+  }
+  if (code === import_shared4.ERROR_CODES.INVALID_REQUEST) return 400;
+  return 500;
+}
+function normalizeError2(error) {
+  return error instanceof import_shared4.SpotPatchError ? error : new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.INTERNAL_ERROR, void 0, { cause: error });
+}
+function assertAuthorized(request, expectedHost, bridgeToken) {
+  if (request.socket.remoteAddress !== "127.0.0.1" || singleHeader(request, "host") !== expectedHost || !tokensMatch(singleHeader(request, import_external_agent_node.SPOTPATCH_BRIDGE_TOKEN_HEADER), bridgeToken)) {
+    throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.BRIDGE_UNAUTHORIZED);
+  }
+}
+async function closeServer(server, sockets) {
+  await new Promise((resolve) => {
+    server.close(() => {
+      resolve();
+    });
+    for (const socket of sockets) {
+      socket.destroy();
+    }
+  });
+}
+async function createExternalHandoffBroker(options) {
+  const bridgeToken = (0, import_node_crypto3.randomBytes)(32).toString("base64url");
+  const sockets = /* @__PURE__ */ new Set();
+  let expectedHost = "";
+  const server = (0, import_node_http.createServer)(
+    { maxHeaderSize: import_shared4.EXTERNAL_HANDOFF_LIMITS.maximumBrokerHeaderBytes },
+    (request, response) => {
+      const handle = async () => {
+        assertAuthorized(request, expectedHost, bridgeToken);
+        if (request.method !== "POST") {
+          throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.INVALID_REQUEST);
+        }
+        const body = await readJsonRequestBody(
+          request,
+          import_shared4.EXTERNAL_HANDOFF_LIMITS.maximumBrokerRequestBytes
+        );
+        if (request.url === import_external_agent_node.SPOTPATCH_BRIDGE_PATHS.status) {
+          const parsed = import_external_agent_node.bridgeStatusRequestSchema.safeParse(body);
+          if (!parsed.success) throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.INVALID_REQUEST);
+          let current = null;
+          try {
+            current = options.store.status();
+          } catch (error) {
+            if (!(error instanceof import_shared4.SpotPatchError) || error.code !== import_shared4.ERROR_CODES.HANDOFF_NOT_FOUND) {
+              throw error;
+            }
+          }
+          writeJson(response, 200, {
+            ok: true,
+            data: Object.freeze({
+              brokerProtocolVersion: import_shared4.EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION,
+              projectKey: options.projectKey,
+              sessionId: options.sessionId,
+              framework: options.framework,
+              current
+            })
+          });
+          return;
+        }
+        if (request.url === import_external_agent_node.SPOTPATCH_BRIDGE_PATHS.current) {
+          const parsed = import_external_agent_node.bridgeCurrentRequestSchema.safeParse(body);
+          if (!parsed.success) throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.INVALID_REQUEST);
+          const snapshot2 = options.store.current(parsed.data.cursor);
+          writeJson(response, 200, {
+            ok: true,
+            data: Object.freeze({ outcome: "handoff", snapshot: snapshot2 })
+          });
+          return;
+        }
+        if (request.url === import_external_agent_node.SPOTPATCH_BRIDGE_PATHS.ack) {
+          const parsed = import_external_agent_node.bridgeAckRequestSchema.safeParse(body);
+          if (!parsed.success) throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.INVALID_REQUEST);
+          const summary = options.store.ack(
+            parsed.data.cursor,
+            parsed.data.connectorInstanceId
+          );
+          writeJson(response, 200, {
+            ok: true,
+            data: Object.freeze({ summary })
+          });
+          return;
+        }
+        if (request.url === import_external_agent_node.SPOTPATCH_BRIDGE_PATHS.wait) {
+          const parsed = import_external_agent_node.bridgeWaitRequestSchema.safeParse(body);
+          if (!parsed.success) throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.INVALID_REQUEST);
+          const controller = new AbortController();
+          const abort = () => {
+            if (!response.writableEnded) controller.abort("bridge-client-closed");
+          };
+          response.once("close", abort);
+          try {
+            const data = await options.store.wait(
+              parsed.data.afterCursor,
+              parsed.data.timeoutMs,
+              controller.signal
+            );
+            writeJson(response, 200, { ok: true, data });
+          } finally {
+            response.removeListener("close", abort);
+          }
+          return;
+        }
+        if (request.url === import_external_agent_node.SPOTPATCH_BRIDGE_PATHS.activeClaim) {
+          const parsed = import_external_agent_node.bridgeActiveClaimRequestSchema.safeParse(body);
+          if (!parsed.success) throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.INVALID_REQUEST);
+          const data = options.activeRegistry.claim(
+            parsed.data.adapterKind,
+            parsed.data.connectorInstanceId,
+            options.store.currentCursor()
+          );
+          writeJson(response, 200, { ok: true, data });
+          return;
+        }
+        if (request.url === import_external_agent_node.SPOTPATCH_BRIDGE_PATHS.activeHeartbeat) {
+          const parsed = import_external_agent_node.bridgeActiveHeartbeatRequestSchema.safeParse(body);
+          if (!parsed.success) throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.INVALID_REQUEST);
+          const data = options.activeRegistry.heartbeat(parsed.data.leaseToken);
+          writeJson(response, 200, { ok: true, data });
+          return;
+        }
+        if (request.url === import_external_agent_node.SPOTPATCH_BRIDGE_PATHS.activeReport) {
+          const parsed = import_external_agent_node.bridgeActiveReportRequestSchema.safeParse(body);
+          if (!parsed.success) throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.INVALID_REQUEST);
+          const data = options.activeRegistry.report(
+            parsed.data.leaseToken,
+            parsed.data.cursor,
+            parsed.data.phase
+          );
+          writeJson(response, 200, { ok: true, data });
+          return;
+        }
+        if (request.url === import_external_agent_node.SPOTPATCH_BRIDGE_PATHS.activeRelease) {
+          const parsed = import_external_agent_node.bridgeActiveReleaseRequestSchema.safeParse(body);
+          if (!parsed.success) throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.INVALID_REQUEST);
+          const data = options.activeRegistry.release(parsed.data.leaseToken);
+          writeJson(response, 200, { ok: true, data });
+          return;
+        }
+        throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.INVALID_REQUEST);
+      };
+      void handle().catch((error) => {
+        if (response.writableEnded || response.destroyed) return;
+        const normalized = normalizeError2(error);
+        if (normalized.code === import_shared4.ERROR_CODES.BRIDGE_BUSY) {
+          response.setHeader("Retry-After", "1");
+        }
+        writeJson(response, statusForError(normalized.code), {
+          ok: false,
+          error: {
+            code: normalized.code,
+            message: "The local SpotPatch bridge request failed."
+          }
+        });
+      });
+    }
+  );
+  server.maxConnections = import_shared4.EXTERNAL_HANDOFF_LIMITS.maximumBrokerSockets;
+  server.headersTimeout = 5e3;
+  server.requestTimeout = import_shared4.EXTERNAL_HANDOFF_LIMITS.maximumWaitMs + 5e3;
+  server.keepAliveTimeout = 1;
+  server.on("connection", (socket) => {
+    if (sockets.size >= import_shared4.EXTERNAL_HANDOFF_LIMITS.maximumBrokerSockets) {
+      socket.destroy();
+      return;
+    }
+    sockets.add(socket);
+    socket.once("close", () => sockets.delete(socket));
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  if (address === null || typeof address === "string" || address.address !== "127.0.0.1") {
+    await closeServer(server, sockets);
+    throw new Error("SpotPatch external Agent broker did not bind IPv4 loopback.");
+  }
+  expectedHost = `127.0.0.1:${String(address.port)}`;
+  let closed = false;
+  let ready = true;
+  server.removeAllListeners("error");
+  server.on("error", () => {
+    ready = false;
+    for (const socket of sockets) socket.destroy();
+  });
+  return Object.freeze({
+    bridgeToken,
+    endpoint: `http://${expectedHost}`,
+    isReady: () => ready && !closed,
+    async close() {
+      if (closed) return;
+      closed = true;
+      ready = false;
+      await closeServer(server, sockets);
+    }
+  });
+}
+
+// src/external-handoff/discovery.ts
+var import_node_crypto4 = require("crypto");
+var import_promises = require("fs/promises");
+var import_node_path = __toESM(require("path"), 1);
+var import_shared5 = require("@spotpatch/shared");
+var import_external_agent_node2 = require("@spotpatch/shared/external-agent-node");
+async function syncDirectory(directory) {
+  const handle = await (0, import_promises.open)(directory, "r");
+  try {
+    await handle.sync();
+  } catch (error) {
+    const code = error.code;
+    if (code !== "EINVAL" && code !== "ENOTSUP") {
+      throw error;
+    }
+  } finally {
+    await handle.close();
+  }
+}
+async function publishExternalHandoffDescriptor(options) {
+  const directory = await (0, import_external_agent_node2.resolveExternalHandoffRuntimeDirectory)(true);
+  const descriptor = import_external_agent_node2.externalHandoffDescriptorSchema.parse({
+    schemaVersion: 1,
+    brokerProtocolVersion: import_shared5.EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION,
+    projectKey: await (0, import_external_agent_node2.computeExternalHandoffProjectKey)(options.root),
+    sessionId: options.sessionId,
+    framework: options.framework,
+    endpoint: options.endpoint,
+    bridgeToken: options.bridgeToken,
+    pid: process.pid,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const serialized = JSON.stringify(descriptor);
+  if (Buffer.byteLength(serialized, "utf8") > import_shared5.EXTERNAL_HANDOFF_LIMITS.maximumDescriptorBytes) {
+    throw new RangeError("SpotPatch external Agent descriptor exceeds its limit.");
+  }
+  const destination = import_node_path.default.join(directory, `${descriptor.sessionId}.json`);
+  const temporary = import_node_path.default.join(
+    directory,
+    `.${descriptor.sessionId}.${(0, import_node_crypto4.randomBytes)(8).toString("hex")}.tmp`
+  );
+  let temporaryExists = false;
+  let published = false;
+  let descriptorIdentity = Object.freeze({
+    device: -1,
+    inode: -1
+  });
+  try {
+    const handle = await (0, import_promises.open)(temporary, "wx", 384);
+    temporaryExists = true;
+    try {
+      await handle.writeFile(serialized, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await (0, import_promises.rename)(temporary, destination);
+    temporaryExists = false;
+    published = true;
+    const status = await (0, import_promises.lstat)(destination);
+    const uid = process.getuid?.();
+    if (!status.isFile() || status.isSymbolicLink() || uid === void 0 || status.uid !== uid || (status.mode & 63) !== 0) {
+      throw new Error("SpotPatch external Agent descriptor is not private.");
+    }
+    descriptorIdentity = Object.freeze({ device: status.dev, inode: status.ino });
+    await syncDirectory(directory);
+  } catch (error) {
+    if (temporaryExists) {
+      await (0, import_promises.unlink)(temporary).catch(() => void 0);
+    }
+    if (published) {
+      await (0, import_promises.unlink)(destination).catch(() => void 0);
+    }
+    throw error;
+  }
+  let closed = false;
+  return Object.freeze({
+    descriptor,
+    async close() {
+      if (closed) return;
+      closed = true;
+      await (0, import_promises.lstat)(destination).then(async (status) => {
+        if (status.dev === descriptorIdentity.device && status.ino === descriptorIdentity.inode) {
+          await (0, import_promises.unlink)(destination);
+        }
+      }).catch((error) => {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      });
+      await syncDirectory(directory);
+    }
+  });
+}
+
+// src/external-handoff/fingerprint.ts
+var import_node_crypto5 = require("crypto");
+function canonicalJson(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("Non-finite JSON number.");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+  }
+  throw new TypeError("Unsupported JSON value.");
+}
+function fingerprintExternalHandoffAnnotation(annotation) {
+  return (0, import_node_crypto5.createHash)("sha256").update(canonicalJson(annotation)).digest("hex");
+}
+
+// src/external-handoff/store.ts
+var import_node_crypto6 = require("crypto");
+var import_shared6 = require("@spotpatch/shared");
+function defaultRandomId2() {
+  return (0, import_node_crypto6.randomBytes)(24).toString("base64url");
+}
+function pageSummary(annotation) {
+  let origin = "[unavailable]";
+  try {
+    const url = new URL(annotation.page.url);
+    origin = url.origin === "null" ? "[unavailable]" : url.origin;
+  } catch {
+  }
+  return Object.freeze({ origin, pathname: annotation.page.pathname });
+}
+function summaryOf(current, state) {
+  const snapshot2 = current.snapshot;
+  return Object.freeze({
+    sessionId: snapshot2.session.id,
+    framework: snapshot2.session.framework,
+    revision: snapshot2.revision,
+    cursor: snapshot2.cursor,
+    targetCount: snapshot2.annotation.targets.length,
+    page: pageSummary(snapshot2.annotation),
+    publishedAt: snapshot2.publishedAt,
+    expiresAt: snapshot2.expiresAt,
+    state,
+    pickupCount: current.receipts.size,
+    ...current.pickedUpAt === void 0 ? {} : { pickedUpAt: current.pickedUpAt }
+  });
+}
+function replayResult(record) {
+  return Object.freeze({ ...record.result, replayed: true });
+}
+function createExternalHandoffStore(options) {
+  const clock = options.clock ?? SYSTEM_EXTERNAL_HANDOFF_CLOCK;
+  const randomId = options.randomId ?? defaultRandomId2;
+  const history = [];
+  const idempotency = /* @__PURE__ */ new Map();
+  const waiters = /* @__PURE__ */ new Set();
+  let closed = false;
+  let current;
+  let revision = 0;
+  const requireOpen = () => {
+    if (closed) throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.SESSION_CLOSED);
+  };
+  const archive = (state) => {
+    if (current === void 0) return;
+    history.unshift(summaryOf(current, state));
+    history.length = Math.min(
+      history.length,
+      import_shared6.EXTERNAL_HANDOFF_LIMITS.maximumHistorySummaries
+    );
+    current = void 0;
+  };
+  const sweep = () => {
+    const monotonicNow = clock.monotonicNow();
+    if (current !== void 0 && monotonicNow >= current.expiresAtMonotonic) {
+      archive("expired");
+    }
+    for (const [requestId, record] of idempotency) {
+      if (monotonicNow >= record.expiresAtMonotonic) idempotency.delete(requestId);
+    }
+  };
+  const knownSummary = (cursor) => {
+    sweep();
+    if (current?.snapshot.cursor === cursor) {
+      return summaryOf(current, "available");
+    }
+    return history.find((summary) => summary.cursor === cursor);
+  };
+  const readCurrent = (cursor) => {
+    requireOpen();
+    sweep();
+    if (current === void 0) {
+      const prior = cursor === void 0 ? void 0 : knownSummary(cursor);
+      throw new import_shared6.SpotPatchError(
+        prior?.state === "expired" ? import_shared6.ERROR_CODES.HANDOFF_EXPIRED : cursor === void 0 ? import_shared6.ERROR_CODES.HANDOFF_NOT_FOUND : import_shared6.ERROR_CODES.HANDOFF_CURSOR_INVALID
+      );
+    }
+    if (cursor !== void 0 && cursor !== current.snapshot.cursor) {
+      const prior = knownSummary(cursor);
+      throw new import_shared6.SpotPatchError(
+        prior?.state === "expired" ? import_shared6.ERROR_CODES.HANDOFF_EXPIRED : import_shared6.ERROR_CODES.HANDOFF_CURSOR_INVALID
+      );
+    }
+    return current.snapshot;
+  };
+  const findReplay = (requestId, fingerprint) => {
+    requireOpen();
+    sweep();
+    const record = idempotency.get(requestId);
+    if (record === void 0) return void 0;
+    if (record.fingerprint !== fingerprint) {
+      throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.HANDOFF_VALIDATION_FAILED);
+    }
+    return replayResult(record);
+  };
+  const settleWaiters = (result) => {
+    const pending = [...waiters];
+    waiters.clear();
+    for (const waiter of pending) waiter.resolve(result);
+  };
+  return Object.freeze({
+    activeWaitCount: () => waiters.size,
+    replay: findReplay,
+    publish(input) {
+      requireOpen();
+      const replayed = findReplay(input.requestId, input.fingerprint);
+      if (replayed !== void 0) return replayed;
+      if (idempotency.size >= import_shared6.EXTERNAL_HANDOFF_LIMITS.maximumRequestIdRecords) {
+        throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.EXTERNAL_HANDOFF_UNAVAILABLE);
+      }
+      const nextRevision = revision + 1;
+      const publishedAtMs = clock.wallNow();
+      const publishedAtMonotonic = clock.monotonicNow();
+      const snapshot2 = Object.freeze({
+        schemaVersion: import_shared6.EXTERNAL_HANDOFF_SNAPSHOT_SCHEMA_VERSION,
+        cursor: randomId(),
+        session: Object.freeze({ id: options.sessionId, framework: options.framework }),
+        revision: nextRevision,
+        publishedAt: new Date(publishedAtMs).toISOString(),
+        expiresAt: new Date(
+          publishedAtMs + import_shared6.EXTERNAL_HANDOFF_LIMITS.handoffTtlMs
+        ).toISOString(),
+        annotation: input.annotation
+      });
+      if (Buffer.byteLength(JSON.stringify(snapshot2), "utf8") > import_shared6.EXTERNAL_HANDOFF_LIMITS.maximumSnapshotBytes) {
+        throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.HANDOFF_RESPONSE_TOO_LARGE);
+      }
+      const delivery = input.reserve(snapshot2.cursor, nextRevision);
+      if (current !== void 0) archive("superseded");
+      revision = nextRevision;
+      current = {
+        expiresAtMonotonic: publishedAtMonotonic + import_shared6.EXTERNAL_HANDOFF_LIMITS.handoffTtlMs,
+        receipts: /* @__PURE__ */ new Set(),
+        snapshot: snapshot2
+      };
+      const result = Object.freeze({
+        handoff: summaryOf(current, "available"),
+        delivery,
+        replayed: false
+      });
+      idempotency.set(
+        input.requestId,
+        Object.freeze({
+          expiresAtMonotonic: publishedAtMonotonic + import_shared6.EXTERNAL_HANDOFF_LIMITS.requestIdTtlMs,
+          fingerprint: input.fingerprint,
+          result
+        })
+      );
+      settleWaiters(Object.freeze({ outcome: "handoff", snapshot: snapshot2 }));
+      return result;
+    },
+    current: readCurrent,
+    currentCursor() {
+      requireOpen();
+      sweep();
+      return current?.snapshot.cursor ?? null;
+    },
+    status(cursor) {
+      requireOpen();
+      sweep();
+      if (cursor === void 0) {
+        if (current === void 0) {
+          throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.HANDOFF_NOT_FOUND);
+        }
+        return summaryOf(current, "available");
+      }
+      const summary = knownSummary(cursor);
+      if (summary === void 0) {
+        throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.HANDOFF_CURSOR_INVALID);
+      }
+      return summary;
+    },
+    ack(cursor, connectorInstanceId) {
+      const snapshot2 = readCurrent(cursor);
+      if (snapshot2 !== current?.snapshot) {
+        throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.HANDOFF_CURSOR_INVALID);
+      }
+      if (!current.receipts.has(connectorInstanceId)) {
+        if (current.receipts.size >= import_shared6.EXTERNAL_HANDOFF_LIMITS.maximumConnectorReceipts) {
+          throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.BRIDGE_BUSY);
+        }
+        current.receipts.add(connectorInstanceId);
+        current.pickedUpAt = new Date(clock.wallNow()).toISOString();
+      }
+      return summaryOf(current, "available");
+    },
+    async wait(afterCursor, timeoutMs, signal) {
+      requireOpen();
+      sweep();
+      if (afterCursor === void 0 && current !== void 0) {
+        return Object.freeze({ outcome: "handoff", snapshot: current.snapshot });
+      }
+      if (afterCursor !== void 0) {
+        const known = knownSummary(afterCursor);
+        if (known === void 0) {
+          throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.HANDOFF_CURSOR_INVALID);
+        }
+        if (current !== void 0 && current.snapshot.cursor !== afterCursor) {
+          return Object.freeze({ outcome: "handoff", snapshot: current.snapshot });
+        }
+      }
+      if (waiters.size >= import_shared6.EXTERNAL_HANDOFF_LIMITS.maximumWaiters) {
+        throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.BRIDGE_BUSY);
+      }
+      if (signal.aborted) throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.SESSION_CLOSED);
+      return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = () => {
+          if (settled) return false;
+          settled = true;
+          waiters.delete(waiter);
+          clearTimeout(timer);
+          signal.removeEventListener("abort", abort);
+          return true;
+        };
+        const waiter = {
+          reject(error) {
+            if (finish()) reject(error);
+          },
+          resolve(result) {
+            if (finish()) resolve(result);
+          }
+        };
+        const abort = () => {
+          waiter.reject(new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.SESSION_CLOSED));
+        };
+        const timer = setTimeout(() => {
+          waiter.resolve(Object.freeze({ outcome: "timeout" }));
+        }, timeoutMs);
+        timer.unref();
+        signal.addEventListener("abort", abort, { once: true });
+        waiters.add(waiter);
+      });
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      current = void 0;
+      history.length = 0;
+      idempotency.clear();
+      const pending = [...waiters];
+      waiters.clear();
+      for (const waiter of pending) {
+        waiter.reject(new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.SESSION_CLOSED));
+      }
+    }
+  });
+}
+
+// src/external-handoff/service.ts
+function asReplay(result) {
+  return Object.freeze({ ...result, replayed: true });
+}
+function createExternalHandoffService(options) {
+  const activeRegistry = createActiveAdapterRegistry();
+  const store = createExternalHandoffStore({
+    framework: options.framework,
+    sessionId: options.sessionId
+  });
+  const inFlight = /* @__PURE__ */ new Map();
+  let broker;
+  let descriptor;
+  let startPromise;
+  let closePromise;
+  let state = "idle";
+  const isClosed = () => state === "closed";
+  const requireReady = () => {
+    if (state !== "ready" || broker?.isReady() !== true) {
+      throw new import_shared7.SpotPatchError(
+        state === "closed" ? import_shared7.ERROR_CODES.SESSION_CLOSED : import_shared7.ERROR_CODES.EXTERNAL_HANDOFF_UNAVAILABLE
+      );
+    }
+  };
+  const start = async () => {
+    if (state === "ready") return;
+    if (state === "closed") throw new import_shared7.SpotPatchError(import_shared7.ERROR_CODES.SESSION_CLOSED);
+    if (startPromise !== void 0) return startPromise;
+    state = "starting";
+    startPromise = (async () => {
+      let createdBroker;
+      let createdDescriptor;
+      try {
+        const projectKey = await (0, import_external_agent_node3.computeExternalHandoffProjectKey)(options.root);
+        createdBroker = await createExternalHandoffBroker({
+          activeRegistry,
+          framework: options.framework,
+          projectKey,
+          sessionId: options.sessionId,
+          store
+        });
+        createdDescriptor = await publishExternalHandoffDescriptor({
+          bridgeToken: createdBroker.bridgeToken,
+          endpoint: createdBroker.endpoint,
+          framework: options.framework,
+          root: options.root,
+          sessionId: options.sessionId
+        });
+        if (isClosed()) {
+          await createdDescriptor.close();
+          await createdBroker.close();
+          throw new import_shared7.SpotPatchError(import_shared7.ERROR_CODES.SESSION_CLOSED);
+        }
+        broker = createdBroker;
+        descriptor = createdDescriptor;
+        state = "ready";
+      } catch (error) {
+        if (createdDescriptor !== void 0 && descriptor !== createdDescriptor) {
+          await createdDescriptor.close().catch(() => void 0);
+        }
+        if (createdBroker !== void 0 && broker !== createdBroker) {
+          await createdBroker.close().catch(() => void 0);
+        }
+        if (!isClosed()) state = "failed";
+        throw error;
+      }
+    })();
+    return startPromise;
+  };
+  return Object.freeze({
+    start,
+    capability() {
+      const currentCursor = store.currentCursor();
+      const active = activeRegistry.snapshot(currentCursor ?? void 0);
+      return Object.freeze({
+        enabled: true,
+        brokerReady: state === "ready" && broker?.isReady() === true,
+        activeWaitCount: store.activeWaitCount(),
+        snapshotSchemaVersion: import_shared7.EXTERNAL_HANDOFF_SNAPSHOT_SCHEMA_VERSION,
+        brokerProtocolVersion: import_shared7.EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION,
+        activeAdapter: active.activeAdapter,
+        dispatch: currentCursor === null ? null : active.dispatch
+      });
+    },
+    async publish(request, authorize) {
+      requireReady();
+      const fingerprint = fingerprintExternalHandoffAnnotation(request.annotation);
+      const replayed = store.replay(request.requestId, fingerprint);
+      if (replayed !== void 0) return replayed;
+      const pending = inFlight.get(request.requestId);
+      if (pending !== void 0) {
+        if (pending.fingerprint !== fingerprint) {
+          throw new import_shared7.SpotPatchError(import_shared7.ERROR_CODES.HANDOFF_VALIDATION_FAILED);
+        }
+        return asReplay(await pending.promise);
+      }
+      activeRegistry.assertPublishable();
+      const promise = (async () => {
+        const annotation = await authorize(request.annotation);
+        return store.publish({
+          annotation,
+          fingerprint,
+          requestId: request.requestId,
+          reserve: activeRegistry.reserve
+        });
+      })();
+      const activePublish = Object.freeze({ fingerprint, promise });
+      inFlight.set(request.requestId, activePublish);
+      try {
+        return await promise;
+      } finally {
+        if (inFlight.get(request.requestId) === activePublish) {
+          inFlight.delete(request.requestId);
+        }
+      }
+    },
+    status(cursor) {
+      requireReady();
+      const handoff = store.status(cursor);
+      const active = activeRegistry.snapshot(cursor ?? handoff.cursor);
+      return Object.freeze({
+        handoff,
+        activeAdapter: active.activeAdapter,
+        dispatch: active.dispatch
+      });
+    },
+    resolveDelivery(cursor) {
+      requireReady();
+      const handoff = store.status(cursor);
+      const active = activeRegistry.resolveDelivery(cursor);
+      return Object.freeze({
+        handoff,
+        activeAdapter: active.activeAdapter,
+        dispatch: active.dispatch
+      });
+    },
+    close() {
+      closePromise ??= (async () => {
+        if (state === "closed") return;
+        state = "closed";
+        activeRegistry.close();
+        store.close();
+        inFlight.clear();
+        await startPromise?.catch(() => void 0);
+        const publishedDescriptor = descriptor;
+        descriptor = void 0;
+        const activeBroker = broker;
+        broker = void 0;
+        await publishedDescriptor?.close().catch(() => void 0);
+        await activeBroker?.close().catch(() => void 0);
+      })();
+      return closePromise;
+    }
+  });
+}
+
 // src/environment-ai.ts
 var AI_ENVIRONMENT_NAMES = Object.freeze({
   authentication: "SPOTPATCH_AI_AUTHENTICATION",
@@ -611,46 +1670,46 @@ function resolveEnvironmentAiConfiguration(environment) {
 }
 
 // src/integration/file-plan.ts
-var import_node_crypto2 = require("crypto");
-var import_promises = require("fs/promises");
-var import_node_path = __toESM(require("path"), 1);
+var import_node_crypto7 = require("crypto");
+var import_promises2 = require("fs/promises");
+var import_node_path2 = __toESM(require("path"), 1);
 function isMissingPathError(error) {
   return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
 function isPathWithin(root, target) {
-  const relative = import_node_path.default.relative(root, target);
-  return relative === "" || relative !== ".." && !relative.startsWith(`..${import_node_path.default.sep}`) && !import_node_path.default.isAbsolute(relative);
+  const relative = import_node_path2.default.relative(root, target);
+  return relative === "" || relative !== ".." && !relative.startsWith(`..${import_node_path2.default.sep}`) && !import_node_path2.default.isAbsolute(relative);
 }
 function relativePathWithin(root, target) {
-  const relative = import_node_path.default.relative(root, target);
+  const relative = import_node_path2.default.relative(root, target);
   if (relative.length === 0 || !isPathWithin(root, target)) {
     throw new Error("SpotPatch init refuses to modify a path outside the app root.");
   }
-  return relative.split(import_node_path.default.sep).join("/");
+  return relative.split(import_node_path2.default.sep).join("/");
 }
 async function integrationPathExists(absolutePath) {
   try {
-    await (0, import_promises.access)(absolutePath);
+    await (0, import_promises2.access)(absolutePath);
     return true;
   } catch {
     return false;
   }
 }
 async function readIntegrationFile(absolutePath) {
-  const metadata = await (0, import_promises.lstat)(absolutePath);
+  const metadata = await (0, import_promises2.lstat)(absolutePath);
   if (!metadata.isFile() || metadata.isSymbolicLink()) {
     throw new Error(
-      `SpotPatch refuses to modify the non-regular file ${import_node_path.default.basename(absolutePath)}.`
+      `SpotPatch refuses to modify the non-regular file ${import_node_path2.default.basename(absolutePath)}.`
     );
   }
-  return (0, import_promises.readFile)(absolutePath, "utf8");
+  return (0, import_promises2.readFile)(absolutePath, "utf8");
 }
 function createIntegrationFileChange(appRoot, absolutePath, nextContent, previousContent) {
   if (previousContent === nextContent) {
     return void 0;
   }
-  const root = import_node_path.default.resolve(appRoot);
-  const target = import_node_path.default.resolve(absolutePath);
+  const root = import_node_path2.default.resolve(appRoot);
+  const target = import_node_path2.default.resolve(absolutePath);
   return Object.freeze({
     absolutePath: target,
     nextContent,
@@ -659,19 +1718,19 @@ function createIntegrationFileChange(appRoot, absolutePath, nextContent, previou
   });
 }
 function temporaryPath(absolutePath, label) {
-  return import_node_path.default.join(
-    import_node_path.default.dirname(absolutePath),
-    `.${import_node_path.default.basename(absolutePath)}.spotpatch-${label}-${String(process.pid)}-${(0, import_node_crypto2.randomBytes)(8).toString("hex")}`
+  return import_node_path2.default.join(
+    import_node_path2.default.dirname(absolutePath),
+    `.${import_node_path2.default.basename(absolutePath)}.spotpatch-${label}-${String(process.pid)}-${(0, import_node_crypto7.randomBytes)(8).toString("hex")}`
   );
 }
 async function writeAtomic(absolutePath, content, mode) {
-  await (0, import_promises.mkdir)(import_node_path.default.dirname(absolutePath), { recursive: true });
+  await (0, import_promises2.mkdir)(import_node_path2.default.dirname(absolutePath), { recursive: true });
   const stagedPath = temporaryPath(absolutePath, "stage");
   try {
-    await (0, import_promises.writeFile)(stagedPath, content, { encoding: "utf8", flag: "wx", mode });
-    await (0, import_promises.rename)(stagedPath, absolutePath);
+    await (0, import_promises2.writeFile)(stagedPath, content, { encoding: "utf8", flag: "wx", mode });
+    await (0, import_promises2.rename)(stagedPath, absolutePath);
   } catch (error) {
-    await (0, import_promises.unlink)(stagedPath).catch(() => void 0);
+    await (0, import_promises2.unlink)(stagedPath).catch(() => void 0);
     throw error;
   }
 }
@@ -683,21 +1742,21 @@ async function rollbackChange(change) {
     );
   }
   if (change.previousContent === void 0) {
-    await (0, import_promises.unlink)(change.absolutePath);
+    await (0, import_promises2.unlink)(change.absolutePath);
     return;
   }
-  const mode = (await (0, import_promises.stat)(change.absolutePath)).mode & 511;
+  const mode = (await (0, import_promises2.stat)(change.absolutePath)).mode & 511;
   await writeAtomic(change.absolutePath, change.previousContent, mode);
 }
 async function assertSafeTarget(appRoot, realAppRoot, change) {
-  const target = import_node_path.default.resolve(change.absolutePath);
+  const target = import_node_path2.default.resolve(change.absolutePath);
   const relativePath = relativePathWithin(appRoot, target);
-  if (target !== change.absolutePath || relativePath !== change.relativePath || import_node_path.default.dirname(target) === target) {
+  if (target !== change.absolutePath || relativePath !== change.relativePath || import_node_path2.default.dirname(target) === target) {
     throw new Error("SpotPatch init received an invalid integration file plan.");
   }
   let targetMetadata;
   try {
-    targetMetadata = await (0, import_promises.lstat)(target);
+    targetMetadata = await (0, import_promises2.lstat)(target);
   } catch (error) {
     if (!isMissingPathError(error)) {
       throw error;
@@ -708,8 +1767,8 @@ async function assertSafeTarget(appRoot, realAppRoot, change) {
       `SpotPatch refuses to modify the symbolic link ${change.relativePath}.`
     );
   }
-  const containmentAnchor = await (0, import_promises.realpath)(
-    targetMetadata === void 0 ? import_node_path.default.dirname(target) : target
+  const containmentAnchor = await (0, import_promises2.realpath)(
+    targetMetadata === void 0 ? import_node_path2.default.dirname(target) : target
   );
   if (!isPathWithin(realAppRoot, containmentAnchor)) {
     throw new Error("SpotPatch init refuses to modify a path outside the app root.");
@@ -718,7 +1777,7 @@ async function assertSafeTarget(appRoot, realAppRoot, change) {
 async function assertCurrentBaseline(change) {
   if (change.previousContent === void 0) {
     try {
-      await (0, import_promises.lstat)(change.absolutePath);
+      await (0, import_promises2.lstat)(change.absolutePath);
     } catch (error) {
       if (isMissingPathError(error)) {
         return;
@@ -740,8 +1799,8 @@ async function applyIntegrationPlan(plan) {
   if (plan.changes.length === 0) {
     return;
   }
-  const appRoot = import_node_path.default.resolve(plan.appRoot);
-  const realAppRoot = await (0, import_promises.realpath)(appRoot);
+  const appRoot = import_node_path2.default.resolve(plan.appRoot);
+  const realAppRoot = await (0, import_promises2.realpath)(appRoot);
   const targets = /* @__PURE__ */ new Set();
   for (const change of plan.changes) {
     if (targets.has(change.absolutePath)) {
@@ -755,7 +1814,7 @@ async function applyIntegrationPlan(plan) {
   try {
     for (const change of plan.changes) {
       await assertCurrentBaseline(change);
-      const mode = change.previousContent === void 0 ? 384 : (await (0, import_promises.stat)(change.absolutePath)).mode & 511;
+      const mode = change.previousContent === void 0 ? 384 : (await (0, import_promises2.stat)(change.absolutePath)).mode & 511;
       await writeAtomic(change.absolutePath, change.nextContent, mode);
       applied.push(change);
     }
@@ -776,7 +1835,7 @@ async function applyIntegrationPlan(plan) {
 }
 
 // src/options.ts
-var import_shared2 = require("@spotpatch/shared");
+var import_shared8 = require("@spotpatch/shared");
 var import_zod = require("zod");
 var DEFAULT_EXCLUDE = Object.freeze([
   /node_modules/,
@@ -811,8 +1870,9 @@ var DEFAULT_OPTIONS = Object.freeze({
   dataFlow: Object.freeze({
     enabled: false,
     runtime: "dispatch",
-    limits: import_shared2.DEFAULT_DATA_FLOW_LIMITS
-  })
+    limits: import_shared8.DEFAULT_DATA_FLOW_LIMITS
+  }),
+  externalAgent: Object.freeze({ enabled: false })
 });
 var PROFILE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 var ENV_NAME_PATTERN = /^[A-Z][A-Z0-9_]{1,127}$/;
@@ -857,7 +1917,7 @@ var aiOptionsSchema = import_zod.z.strictObject({
   defaultProvider: import_zod.z.string(),
   execution: import_zod.z.strictObject({
     isolation: import_zod.z.literal("git-worktree").optional(),
-    applyMode: import_zod.z.enum(import_shared2.AGENT_APPLY_MODES).optional(),
+    applyMode: import_zod.z.enum(import_shared8.AGENT_APPLY_MODES).optional(),
     checks: import_zod.z.record(import_zod.z.string(), agentCheckSchema).optional(),
     limits: agentLimitsSchema
   }).optional()
@@ -903,18 +1963,18 @@ function normalizeProviderBaseURL(value) {
 }
 function resolveLimits(limits) {
   const resolved = Object.freeze({
-    maxTurns: limits?.maxTurns ?? import_shared2.DEFAULT_AGENT_LIMITS.maxTurns,
-    maxToolCalls: limits?.maxToolCalls ?? import_shared2.DEFAULT_AGENT_LIMITS.maxToolCalls,
-    maxChangedFiles: limits?.maxChangedFiles ?? import_shared2.DEFAULT_AGENT_LIMITS.maxChangedFiles,
-    maxDiffBytes: limits?.maxDiffBytes ?? import_shared2.DEFAULT_AGENT_LIMITS.maxDiffBytes,
-    maxReadBytesPerFile: limits?.maxReadBytesPerFile ?? import_shared2.DEFAULT_AGENT_LIMITS.maxReadBytesPerFile,
-    maxToolOutputCharacters: limits?.maxToolOutputCharacters ?? import_shared2.DEFAULT_AGENT_LIMITS.maxToolOutputCharacters,
-    maxProviderResponseBytes: limits?.maxProviderResponseBytes ?? import_shared2.DEFAULT_AGENT_LIMITS.maxProviderResponseBytes,
-    providerConnectTimeoutMs: limits?.providerConnectTimeoutMs ?? import_shared2.DEFAULT_AGENT_LIMITS.providerConnectTimeoutMs,
-    providerFirstByteTimeoutMs: limits?.providerFirstByteTimeoutMs ?? import_shared2.DEFAULT_AGENT_LIMITS.providerFirstByteTimeoutMs,
-    providerIdleTimeoutMs: limits?.providerIdleTimeoutMs ?? import_shared2.DEFAULT_AGENT_LIMITS.providerIdleTimeoutMs,
-    checkTimeoutMs: limits?.checkTimeoutMs ?? import_shared2.DEFAULT_AGENT_LIMITS.checkTimeoutMs,
-    jobTimeoutMs: limits?.jobTimeoutMs ?? import_shared2.DEFAULT_AGENT_LIMITS.jobTimeoutMs
+    maxTurns: limits?.maxTurns ?? import_shared8.DEFAULT_AGENT_LIMITS.maxTurns,
+    maxToolCalls: limits?.maxToolCalls ?? import_shared8.DEFAULT_AGENT_LIMITS.maxToolCalls,
+    maxChangedFiles: limits?.maxChangedFiles ?? import_shared8.DEFAULT_AGENT_LIMITS.maxChangedFiles,
+    maxDiffBytes: limits?.maxDiffBytes ?? import_shared8.DEFAULT_AGENT_LIMITS.maxDiffBytes,
+    maxReadBytesPerFile: limits?.maxReadBytesPerFile ?? import_shared8.DEFAULT_AGENT_LIMITS.maxReadBytesPerFile,
+    maxToolOutputCharacters: limits?.maxToolOutputCharacters ?? import_shared8.DEFAULT_AGENT_LIMITS.maxToolOutputCharacters,
+    maxProviderResponseBytes: limits?.maxProviderResponseBytes ?? import_shared8.DEFAULT_AGENT_LIMITS.maxProviderResponseBytes,
+    providerConnectTimeoutMs: limits?.providerConnectTimeoutMs ?? import_shared8.DEFAULT_AGENT_LIMITS.providerConnectTimeoutMs,
+    providerFirstByteTimeoutMs: limits?.providerFirstByteTimeoutMs ?? import_shared8.DEFAULT_AGENT_LIMITS.providerFirstByteTimeoutMs,
+    providerIdleTimeoutMs: limits?.providerIdleTimeoutMs ?? import_shared8.DEFAULT_AGENT_LIMITS.providerIdleTimeoutMs,
+    checkTimeoutMs: limits?.checkTimeoutMs ?? import_shared8.DEFAULT_AGENT_LIMITS.checkTimeoutMs,
+    jobTimeoutMs: limits?.jobTimeoutMs ?? import_shared8.DEFAULT_AGENT_LIMITS.jobTimeoutMs
   });
   for (const [name, value] of Object.entries(resolved)) {
     if (!Number.isSafeInteger(value) || value <= 0) {
@@ -1119,7 +2179,7 @@ function resolveDataFlowOptions(options) {
   return Object.freeze({
     enabled: true,
     runtime,
-    limits: import_shared2.DEFAULT_DATA_FLOW_LIMITS
+    limits: import_shared8.DEFAULT_DATA_FLOW_LIMITS
   });
 }
 function createRuntimeDataFlowConfig(options) {
@@ -1138,6 +2198,9 @@ function resolveOptions(options = {}, environmentAi) {
   if (options.trustedFastMode !== void 0 && typeof options.trustedFastMode !== "boolean") {
     throw new RangeError("SpotPatch trustedFastMode must be a boolean.");
   }
+  if (options.externalAgent !== void 0 && typeof options.externalAgent !== "boolean") {
+    throw new RangeError("SpotPatch externalAgent must be a boolean.");
+  }
   const budget = Object.freeze({
     ...DEFAULT_OPTIONS.budget,
     ...options.budget
@@ -1146,15 +2209,15 @@ function resolveOptions(options = {}, environmentAi) {
   const maxTargets = options.maxTargets ?? DEFAULT_OPTIONS.maxTargets;
   const locale = options.locale ?? DEFAULT_OPTIONS.locale;
   const editor = options.editor ?? DEFAULT_OPTIONS.editor;
-  if (!import_shared2.SPOTPATCH_LOCALE_PREFERENCES.includes(locale)) {
+  if (!import_shared8.SPOTPATCH_LOCALE_PREFERENCES.includes(locale)) {
     throw new RangeError("SpotPatch locale must be auto, en-US, or zh-CN.");
   }
-  if (!import_shared2.SPOTPATCH_EDITOR_PREFERENCES.includes(editor)) {
+  if (!import_shared8.SPOTPATCH_EDITOR_PREFERENCES.includes(editor)) {
     throw new RangeError("SpotPatch editor must be auto, vscode, or cursor.");
   }
-  if (!Number.isSafeInteger(maxTargets) || maxTargets < 1 || maxTargets > import_shared2.MAX_ANNOTATION_TARGETS) {
+  if (!Number.isSafeInteger(maxTargets) || maxTargets < 1 || maxTargets > import_shared8.MAX_ANNOTATION_TARGETS) {
     throw new RangeError(
-      `SpotPatch maxTargets must be an integer between 1 and ${String(import_shared2.MAX_ANNOTATION_TARGETS)}.`
+      `SpotPatch maxTargets must be an integer between 1 and ${String(import_shared8.MAX_ANNOTATION_TARGETS)}.`
     );
   }
   const resolved = {
@@ -1170,7 +2233,10 @@ function resolveOptions(options = {}, environmentAi) {
     locale,
     maxTargets,
     ai: resolveAiOptions(options.ai ?? environmentAi),
-    dataFlow: resolveDataFlowOptions(options.dataFlow)
+    dataFlow: resolveDataFlowOptions(options.dataFlow),
+    externalAgent: Object.freeze({
+      enabled: options.externalAgent ?? DEFAULT_OPTIONS.externalAgent.enabled
+    })
   };
   if (resolved.shortcut.trim().length === 0 || resolved.shortcut.length > 128 || resolved.shortcut.includes("\0")) {
     throw new RangeError("SpotPatch shortcut is invalid.");
@@ -1180,9 +2246,9 @@ function resolveOptions(options = {}, environmentAi) {
 
 // src/project-validation.ts
 var import_node_child_process = require("child_process");
-var import_promises2 = require("fs/promises");
+var import_promises3 = require("fs/promises");
 var import_node_module = require("module");
-var import_node_path2 = __toESM(require("path"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
 var import_node_util = require("util");
 var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
 var TYPESCRIPT_CHECK_ID = "spotpatch-typecheck";
@@ -1192,19 +2258,19 @@ function isRecord(value) {
 }
 async function isRegularFile(absolutePath) {
   try {
-    const metadata = await (0, import_promises2.lstat)(absolutePath);
+    const metadata = await (0, import_promises3.lstat)(absolutePath);
     return metadata.isFile() && !metadata.isSymbolicLink();
   } catch {
     return false;
   }
 }
 async function readManifest(appRoot) {
-  const manifestPath = import_node_path2.default.join(appRoot, "package.json");
+  const manifestPath = import_node_path3.default.join(appRoot, "package.json");
   if (!await isRegularFile(manifestPath)) {
     return void 0;
   }
   try {
-    const value = JSON.parse(await (0, import_promises2.readFile)(manifestPath, "utf8"));
+    const value = JSON.parse(await (0, import_promises3.readFile)(manifestPath, "utf8"));
     return isRecord(value) ? value : void 0;
   } catch {
     return void 0;
@@ -1227,9 +2293,9 @@ async function findGitRoot(appRoot) {
       timeout: 5e3,
       windowsHide: true
     });
-    const root = await (0, import_promises2.realpath)(result.stdout.trim());
-    const relative = import_node_path2.default.relative(root, appRoot);
-    if (relative === "" || !relative.startsWith(`..${import_node_path2.default.sep}`) && relative !== ".." && !import_node_path2.default.isAbsolute(relative)) {
+    const root = await (0, import_promises3.realpath)(result.stdout.trim());
+    const relative = import_node_path3.default.relative(root, appRoot);
+    if (relative === "" || !relative.startsWith(`..${import_node_path3.default.sep}`) && relative !== ".." && !import_node_path3.default.isAbsolute(relative)) {
       return root;
     }
   } catch {
@@ -1238,22 +2304,22 @@ async function findGitRoot(appRoot) {
   return void 0;
 }
 async function resolveTypeScriptCli(appRoot) {
-  const resolveFromApplication = (0, import_node_module.createRequire)(import_node_path2.default.join(appRoot, "package.json"));
+  const resolveFromApplication = (0, import_node_module.createRequire)(import_node_path3.default.join(appRoot, "package.json"));
   try {
     const packagePath = resolveFromApplication.resolve("typescript/package.json");
-    const cliPath = import_node_path2.default.join(import_node_path2.default.dirname(packagePath), "bin", "tsc");
-    await (0, import_promises2.access)(cliPath);
-    return await (0, import_promises2.realpath)(cliPath);
+    const cliPath = import_node_path3.default.join(import_node_path3.default.dirname(packagePath), "bin", "tsc");
+    await (0, import_promises3.access)(cliPath);
+    return await (0, import_promises3.realpath)(cliPath);
   } catch {
     return void 0;
   }
 }
 function portableRelativePath(from, to) {
-  return import_node_path2.default.relative(from, to).split(import_node_path2.default.sep).join("/");
+  return import_node_path3.default.relative(from, to).split(import_node_path3.default.sep).join("/");
 }
 async function discoverProjectValidationCheck(options) {
-  const appRoot = await (0, import_promises2.realpath)(options.appRoot);
-  const tsconfigPath = import_node_path2.default.join(appRoot, "tsconfig.json");
+  const appRoot = await (0, import_promises3.realpath)(options.appRoot);
+  const tsconfigPath = import_node_path3.default.join(appRoot, "tsconfig.json");
   const [manifest, projectRoot, hasTsconfig] = await Promise.all([
     readManifest(appRoot),
     findGitRoot(appRoot),
@@ -1341,16 +2407,16 @@ async function resolveProjectOptions(input) {
 }
 
 // src/registry/source-registry.ts
-var import_node_path3 = __toESM(require("path"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
 
 // src/registry/source-id.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto8 = require("crypto");
 var SOURCE_ID_BYTES = 8;
-var createRandomSourceId = () => (0, import_node_crypto3.randomBytes)(SOURCE_ID_BYTES).toString("base64url");
+var createRandomSourceId = () => (0, import_node_crypto8.randomBytes)(SOURCE_ID_BYTES).toString("base64url");
 
 // src/registry/source-registry.ts
 function normalizeAbsolutePath(absolutePath) {
-  return import_node_path3.default.normalize(import_node_path3.default.resolve(absolutePath));
+  return import_node_path4.default.normalize(import_node_path4.default.resolve(absolutePath));
 }
 function createSourceRegistry(options = {}) {
   const createId = options.createId ?? createRandomSourceId;
@@ -1407,20 +2473,20 @@ function createSourceRegistry(options = {}) {
 }
 
 // src/server/middleware.ts
-var import_shared11 = require("@spotpatch/shared");
+var import_shared18 = require("@spotpatch/shared");
 
-// src/server/agent-http.ts
-var import_shared7 = require("@spotpatch/shared");
+// src/external-handoff/browser-http.ts
+var import_shared12 = require("@spotpatch/shared");
 
-// src/server/agent-request.ts
-var import_promises5 = require("fs/promises");
-var import_node_path6 = __toESM(require("path"), 1);
-var import_shared5 = require("@spotpatch/shared");
+// src/server/annotation-authorizer.ts
+var import_promises6 = require("fs/promises");
+var import_node_path7 = __toESM(require("path"), 1);
+var import_shared11 = require("@spotpatch/shared");
 
 // src/server/source-context.ts
-var import_promises4 = require("fs/promises");
-var import_node_path5 = __toESM(require("path"), 1);
-var import_shared4 = require("@spotpatch/shared");
+var import_promises5 = require("fs/promises");
+var import_node_path6 = __toESM(require("path"), 1);
+var import_shared10 = require("@spotpatch/shared");
 
 // src/server/extract-code-context.ts
 var import_oxc_parser = require("oxc-parser");
@@ -1649,16 +2715,9 @@ function extractCodeContext(options) {
 }
 
 // src/server/source-file.ts
-var import_promises3 = require("fs/promises");
-var import_node_path4 = __toESM(require("path"), 1);
-var import_shared3 = require("@spotpatch/shared");
-
-// src/server/constants.ts
-var MAX_REQUEST_BODY_BYTES = 32 * 1024;
-var MAX_AGENT_REQUEST_BODY_BYTES = 256 * 1024;
-var MAX_SOURCE_FILE_BYTES = 1024 * 1024;
-
-// src/server/source-file.ts
+var import_promises4 = require("fs/promises");
+var import_node_path5 = __toESM(require("path"), 1);
+var import_shared9 = require("@spotpatch/shared");
 var ALLOWED_EXTENSIONS = /* @__PURE__ */ new Set([".jsx", ".tsx"]);
 function isMissingFileError(error) {
   return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
@@ -1668,56 +2727,56 @@ async function assertInsideRoot(root, candidate) {
   let realCandidate;
   try {
     [realRoot, realCandidate] = await Promise.all([
-      (0, import_promises3.realpath)(root),
-      (0, import_promises3.realpath)(candidate)
+      (0, import_promises4.realpath)(root),
+      (0, import_promises4.realpath)(candidate)
     ]);
   } catch (error) {
     if (isMissingFileError(error)) {
-      throw new import_shared3.SpotPatchError(import_shared3.ERROR_CODES.SOURCE_NOT_FOUND, void 0, {
+      throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.SOURCE_NOT_FOUND, void 0, {
         cause: error
       });
     }
     throw error;
   }
-  const relative = import_node_path4.default.relative(realRoot, realCandidate);
-  const outside = relative.startsWith(`..${import_node_path4.default.sep}`) || relative === ".." || import_node_path4.default.isAbsolute(relative);
+  const relative = import_node_path5.default.relative(realRoot, realCandidate);
+  const outside = relative.startsWith(`..${import_node_path5.default.sep}`) || relative === ".." || import_node_path5.default.isAbsolute(relative);
   if (outside) {
-    throw new import_shared3.SpotPatchError(import_shared3.ERROR_CODES.SOURCE_OUTSIDE_ROOT);
+    throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.SOURCE_OUTSIDE_ROOT);
   }
   return realCandidate;
 }
 async function resolveSourceFile(options) {
   const registeredPath = options.registry.resolve(options.fileId);
   if (registeredPath === void 0) {
-    throw new import_shared3.SpotPatchError(import_shared3.ERROR_CODES.SOURCE_NOT_FOUND);
+    throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.SOURCE_NOT_FOUND);
   }
   const sourcePath = await assertInsideRoot(options.root, registeredPath);
-  if (!ALLOWED_EXTENSIONS.has(import_node_path4.default.extname(sourcePath).toLowerCase())) {
-    throw new import_shared3.SpotPatchError(import_shared3.ERROR_CODES.SOURCE_NOT_FOUND);
+  if (!ALLOWED_EXTENSIONS.has(import_node_path5.default.extname(sourcePath).toLowerCase())) {
+    throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.SOURCE_NOT_FOUND);
   }
   let sourceStat;
   try {
-    sourceStat = await (0, import_promises3.stat)(sourcePath);
+    sourceStat = await (0, import_promises4.stat)(sourcePath);
   } catch (error) {
     if (isMissingFileError(error)) {
-      throw new import_shared3.SpotPatchError(import_shared3.ERROR_CODES.SOURCE_NOT_FOUND, void 0, {
+      throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.SOURCE_NOT_FOUND, void 0, {
         cause: error
       });
     }
     throw error;
   }
   if (!sourceStat.isFile()) {
-    throw new import_shared3.SpotPatchError(import_shared3.ERROR_CODES.SOURCE_NOT_FOUND);
+    throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.SOURCE_NOT_FOUND);
   }
   if (sourceStat.size > MAX_SOURCE_FILE_BYTES) {
-    throw new import_shared3.SpotPatchError(import_shared3.ERROR_CODES.SOURCE_TOO_LARGE);
+    throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.SOURCE_TOO_LARGE);
   }
   return sourcePath;
 }
 
 // src/server/source-context.ts
 function toDisplayPath(root, sourcePath) {
-  return import_node_path5.default.relative(root, sourcePath).split(import_node_path5.default.sep).join("/");
+  return import_node_path6.default.relative(root, sourcePath).split(import_node_path6.default.sep).join("/");
 }
 async function readSourceContext(options) {
   const sourcePath = await resolveSourceFile({
@@ -1727,10 +2786,10 @@ async function readSourceContext(options) {
   });
   let source;
   try {
-    source = await (0, import_promises4.readFile)(sourcePath, "utf8");
+    source = await (0, import_promises5.readFile)(sourcePath, "utf8");
   } catch (error) {
     if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
-      throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.SOURCE_NOT_FOUND, void 0, {
+      throw new import_shared10.SpotPatchError(import_shared10.ERROR_CODES.SOURCE_NOT_FOUND, void 0, {
         cause: error
       });
     }
@@ -1738,13 +2797,13 @@ async function readSourceContext(options) {
   }
   const lines = source.split(/\r?\n/);
   if (options.request.line > lines.length) {
-    throw new import_shared4.SpotPatchError(import_shared4.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared10.SpotPatchError(import_shared10.ERROR_CODES.INVALID_REQUEST);
   }
-  const extension = import_node_path5.default.extname(sourcePath).toLowerCase();
+  const extension = import_node_path6.default.extname(sourcePath).toLowerCase();
   return extractCodeContext({
     source,
     sourcePath,
-    relativePath: toDisplayPath(await (0, import_promises4.realpath)(options.root), sourcePath),
+    relativePath: toDisplayPath(await (0, import_promises5.realpath)(options.root), sourcePath),
     language: extension === ".tsx" ? "tsx" : "jsx",
     line: options.request.line,
     column: options.request.column,
@@ -1753,7 +2812,17 @@ async function readSourceContext(options) {
   });
 }
 
-// src/server/agent-request.ts
+// src/server/annotation-authorizer.ts
+function sanitizePageContext(page) {
+  return Object.freeze({
+    url: (0, import_shared11.sanitizeUrl)(page.url, page.url),
+    pathname: (0, import_shared11.redactSensitiveText)(page.pathname),
+    title: (0, import_shared11.redactSensitiveText)(page.title),
+    viewportWidth: page.viewportWidth,
+    viewportHeight: page.viewportHeight,
+    devicePixelRatio: page.devicePixelRatio
+  });
+}
 function compactSourceRef(source) {
   return Object.freeze({
     origin: source.origin,
@@ -1767,27 +2836,20 @@ function compactSourceRef(source) {
 async function authorizeSourceRef(source, registry, root) {
   const markerOrigin = source.origin === "jsx-host" || source.origin === "dom-ancestor";
   if (markerOrigin && (source.fileId === void 0 || source.line === void 0 || source.column === void 0)) {
-    throw new import_shared5.SpotPatchError(import_shared5.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
   }
   if (source.fileId === void 0) {
     if (source.origin === "none" && source.relativePath !== void 0) {
-      throw new import_shared5.SpotPatchError(import_shared5.ERROR_CODES.INVALID_REQUEST);
+      throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
     }
     return compactSourceRef(source);
   }
-  const sourcePath = await resolveSourceFile({
-    fileId: source.fileId,
-    registry,
-    root
-  });
-  const relativePath = import_node_path6.default.relative(await (0, import_promises5.realpath)(root), sourcePath).split(import_node_path6.default.sep).join("/");
+  const sourcePath = await resolveSourceFile({ fileId: source.fileId, registry, root });
+  const relativePath = import_node_path7.default.relative(await (0, import_promises6.realpath)(root), sourcePath).split(import_node_path7.default.sep).join("/");
   if (source.relativePath !== void 0 && source.relativePath !== relativePath) {
-    throw new import_shared5.SpotPatchError(import_shared5.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
   }
-  return Object.freeze({
-    ...compactSourceRef(source),
-    relativePath
-  });
+  return Object.freeze({ ...compactSourceRef(source), relativePath });
 }
 function freezeMatchedRule(rule) {
   return Object.freeze({
@@ -1821,7 +2883,7 @@ async function authorizeTarget(target, input) {
     maxLines: input.options.budget.maxCodeLines
   });
   if (marker === void 0 && target.code !== void 0) {
-    throw new import_shared5.SpotPatchError(import_shared5.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
   }
   const code = marker === void 0 ? void 0 : await readSourceContext({
     request: marker,
@@ -1831,11 +2893,11 @@ async function authorizeTarget(target, input) {
     maxLines: input.options.budget.maxCodeLines
   });
   if (target.code !== void 0 && target.code.relativePath !== code?.relativePath) {
-    throw new import_shared5.SpotPatchError(import_shared5.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
   }
   return Object.freeze({
     instruction: target.instruction,
-    ...target.page === void 0 ? {} : { page: Object.freeze({ ...target.page }) },
+    ...target.page === void 0 ? {} : { page: sanitizePageContext(target.page) },
     source,
     react: Object.freeze({
       supported: target.react.supported,
@@ -1863,76 +2925,130 @@ async function authorizeTarget(target, input) {
     warnings: Object.freeze([...target.warnings])
   });
 }
-async function authorizeAgentJobRequest(input) {
-  const requestedTargets = input.request.annotation.targets;
+async function authorizeAnnotation(input) {
+  const requestedTargets = input.annotation.targets;
   if (requestedTargets.length > input.options.maxTargets) {
-    throw new import_shared5.SpotPatchError(import_shared5.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
   }
   const identities = requestedTargets.map(targetIdentity);
   if (new Set(identities).size !== identities.length) {
-    throw new import_shared5.SpotPatchError(import_shared5.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
   }
   const targets = Object.freeze(
     await Promise.all(requestedTargets.map((target) => authorizeTarget(target, input)))
   );
-  const annotation = Object.freeze({
+  return Object.freeze({
     schemaVersion: 3,
-    id: input.request.annotation.id,
-    locale: input.request.annotation.locale,
-    page: Object.freeze({ ...input.request.annotation.page }),
+    id: input.annotation.id,
+    locale: input.annotation.locale,
+    page: sanitizePageContext(input.annotation.page),
     targets,
-    createdAt: input.request.annotation.createdAt
-  });
-  return Object.freeze({
-    annotation,
-    ...input.request.applyMode === void 0 ? {} : { applyMode: input.request.applyMode },
-    providerProfileId: input.request.providerProfileId,
-    modelProfileId: input.request.modelProfileId,
-    providerDataConsent: true,
-    ...input.request.trustedFastModeConsent === true ? { trustedFastModeConsent: true } : {},
-    workingTreeMode: input.request.workingTreeMode
+    createdAt: input.annotation.createdAt
   });
 }
 
-// src/server/request-body.ts
-var import_shared6 = require("@spotpatch/shared");
-function isJsonContentType(value) {
-  return value?.split(";", 1)[0]?.trim().toLowerCase() === "application/json";
-}
-async function readJsonRequestBody(request, maximumBytes = MAX_REQUEST_BODY_BYTES) {
-  if (!isJsonContentType(request.headers["content-type"])) {
-    throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.INVALID_REQUEST);
+// src/external-handoff/browser-http.ts
+function matchExternalHandoffBrowserPath(path9) {
+  if (path9 === import_shared12.SPOTPATCH_ENDPOINTS.externalHandoffCapability) return "capability";
+  if (path9 === import_shared12.SPOTPATCH_ENDPOINTS.externalHandoffPublish) return "publish";
+  if (path9 === import_shared12.SPOTPATCH_ENDPOINTS.externalHandoffStatus) return "status";
+  if (path9 === import_shared12.SPOTPATCH_ENDPOINTS.externalHandoffResolveDelivery) {
+    return "resolve-delivery";
   }
-  const declaredLength = Number(request.headers["content-length"]);
-  if (Number.isFinite(declaredLength) && declaredLength > maximumBytes) {
-    throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.INVALID_REQUEST);
+  return void 0;
+}
+function requireService(options) {
+  if (!options.options.externalAgent.enabled || options.service === void 0) {
+    throw new import_shared12.SpotPatchError(import_shared12.ERROR_CODES.EXTERNAL_HANDOFF_DISABLED);
   }
-  const chunks = [];
-  let byteLength = 0;
-  let exceededLimit = false;
-  for await (const rawChunk of request) {
-    const chunk = rawChunk;
-    if (typeof chunk !== "string" && !(chunk instanceof Uint8Array)) {
-      throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.INVALID_REQUEST);
+  return options.service;
+}
+function remapAuthorizationError(error) {
+  if (error instanceof import_shared12.SpotPatchError) {
+    if (error.code === import_shared12.ERROR_CODES.SOURCE_NOT_FOUND || error.code === import_shared12.ERROR_CODES.SOURCE_OUTSIDE_ROOT || error.code === import_shared12.ERROR_CODES.SOURCE_TOO_LARGE) {
+      throw new import_shared12.SpotPatchError(import_shared12.ERROR_CODES.HANDOFF_SOURCE_STALE, void 0, {
+        cause: error
+      });
     }
-    const buffer = Buffer.from(chunk);
-    byteLength += buffer.byteLength;
-    if (byteLength > maximumBytes) {
-      exceededLimit = true;
-      continue;
+    if (error.code === import_shared12.ERROR_CODES.INVALID_REQUEST) {
+      throw new import_shared12.SpotPatchError(import_shared12.ERROR_CODES.HANDOFF_VALIDATION_FAILED, void 0, {
+        cause: error
+      });
     }
-    chunks.push(buffer);
   }
-  if (exceededLimit || byteLength === 0) {
-    throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.INVALID_REQUEST);
+  throw error;
+}
+async function handleExternalHandoffBrowserRequest(request, response, route, options, writeSuccess) {
+  if (request.method !== "POST") {
+    throw new import_shared12.SpotPatchError(import_shared12.ERROR_CODES.INVALID_REQUEST);
   }
-  try {
-    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
-  } catch (error) {
-    throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.INVALID_REQUEST, void 0, {
-      cause: error
-    });
+  const service = requireService(options);
+  if (route === "capability") {
+    const parsed2 = import_shared12.externalHandoffCapabilityRequestSchema.safeParse(
+      await readJsonRequestBody(request)
+    );
+    if (!parsed2.success) throw new import_shared12.SpotPatchError(import_shared12.ERROR_CODES.INVALID_REQUEST);
+    writeSuccess(response, 200, service.capability());
+    return;
+  }
+  if (route === "status") {
+    const parsed2 = import_shared12.externalHandoffStatusRequestSchema.safeParse(
+      await readJsonRequestBody(request)
+    );
+    if (!parsed2.success) throw new import_shared12.SpotPatchError(import_shared12.ERROR_CODES.INVALID_REQUEST);
+    writeSuccess(response, 200, service.status(parsed2.data.cursor));
+    return;
+  }
+  if (route === "resolve-delivery") {
+    const parsed2 = import_shared12.externalHandoffResolveDeliveryRequestSchema.safeParse(
+      await readJsonRequestBody(request)
+    );
+    if (!parsed2.success) throw new import_shared12.SpotPatchError(import_shared12.ERROR_CODES.INVALID_REQUEST);
+    writeSuccess(response, 200, service.resolveDelivery(parsed2.data.cursor));
+    return;
+  }
+  const parsed = import_shared12.externalHandoffPublishRequestSchema.safeParse(
+    await readJsonRequestBody(request, import_shared12.EXTERNAL_HANDOFF_LIMITS.maximumPublishBodyBytes)
+  );
+  if (!parsed.success) {
+    throw new import_shared12.SpotPatchError(import_shared12.ERROR_CODES.HANDOFF_VALIDATION_FAILED);
   }
+  const result = await service.publish(parsed.data, async (annotation) => {
+    try {
+      return await authorizeAnnotation({
+        annotation,
+        options: options.options,
+        registry: options.registry,
+        root: options.root
+      });
+    } catch (error) {
+      remapAuthorizationError(error);
+    }
+  });
+  writeSuccess(response, result.replayed ? 200 : 201, result);
+}
+
+// src/server/agent-http.ts
+var import_shared14 = require("@spotpatch/shared");
+
+// src/server/agent-request.ts
+var import_shared13 = require("@spotpatch/shared");
+async function authorizeAgentJobRequest(input) {
+  const annotation = await authorizeAnnotation({
+    annotation: input.request.annotation,
+    options: input.options,
+    registry: input.registry,
+    root: input.root
+  });
+  return Object.freeze({
+    annotation,
+    ...input.request.applyMode === void 0 ? {} : { applyMode: input.request.applyMode },
+    providerProfileId: input.request.providerProfileId,
+    modelProfileId: input.request.modelProfileId,
+    providerDataConsent: true,
+    ...input.request.trustedFastModeConsent === true ? { trustedFastModeConsent: true } : {},
+    workingTreeMode: input.request.workingTreeMode
+  });
 }
 
 // src/server/agent-http.ts
@@ -1952,21 +3068,21 @@ var EVENT_STREAM_END_STATUSES = /* @__PURE__ */ new Set([
   "reverted",
   "failed"
 ]);
-function matchAgentRequestPath(path8) {
-  if (path8 === import_shared7.SPOTPATCH_ENDPOINTS.agentCapability) {
+function matchAgentRequestPath(path9) {
+  if (path9 === import_shared14.SPOTPATCH_ENDPOINTS.agentCapability) {
     return Object.freeze({ kind: "capability" });
   }
-  if (path8 === import_shared7.SPOTPATCH_ENDPOINTS.agentWorkspaceHealth) {
+  if (path9 === import_shared14.SPOTPATCH_ENDPOINTS.agentWorkspaceHealth) {
     return Object.freeze({ kind: "workspace-health" });
   }
-  if (path8 === import_shared7.SPOTPATCH_ENDPOINTS.agentJobs) {
+  if (path9 === import_shared14.SPOTPATCH_ENDPOINTS.agentJobs) {
     return Object.freeze({ kind: "create-job" });
   }
-  const prefix = `${import_shared7.SPOTPATCH_ENDPOINTS.agentJobs}/`;
-  if (!path8.startsWith(prefix)) {
+  const prefix = `${import_shared14.SPOTPATCH_ENDPOINTS.agentJobs}/`;
+  if (!path9.startsWith(prefix)) {
     return void 0;
   }
-  const segments = path8.slice(prefix.length).split("/");
+  const segments = path9.slice(prefix.length).split("/");
   const jobId = segments[0];
   const action = segments[1];
   if (segments.length !== 2 || jobId === void 0 || !AGENT_JOB_ID_PATTERN.test(jobId) || action === void 0 || !AGENT_JOB_ACTIONS.has(action)) {
@@ -1980,7 +3096,7 @@ function matchAgentRequestPath(path8) {
 }
 function requireAgentManager(options) {
   if (options.agentManager === void 0 || options.options.ai === false) {
-    throw new import_shared7.SpotPatchError(import_shared7.ERROR_CODES.AI_DISABLED);
+    throw new import_shared14.SpotPatchError(import_shared14.ERROR_CODES.AI_DISABLED);
   }
   return options.agentManager;
 }
@@ -2033,13 +3149,13 @@ function streamAgentJobEvents(response, manager, jobId) {
 }
 async function handleCapability(request, response, options, writeSuccess) {
   if (request.method !== "POST") {
-    throw new import_shared7.SpotPatchError(import_shared7.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared14.SpotPatchError(import_shared14.ERROR_CODES.INVALID_REQUEST);
   }
-  const parsed = import_shared7.agentCapabilityRequestSchema.safeParse(
+  const parsed = import_shared14.agentCapabilityRequestSchema.safeParse(
     await readJsonRequestBody(request)
   );
   if (!parsed.success) {
-    throw new import_shared7.SpotPatchError(import_shared7.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared14.SpotPatchError(import_shared14.ERROR_CODES.INVALID_REQUEST);
   }
   const controller = new AbortController();
   const abort = () => {
@@ -2058,13 +3174,13 @@ async function handleCapability(request, response, options, writeSuccess) {
 }
 async function handleCreateJob(request, response, options, writeSuccess) {
   if (request.method !== "POST") {
-    throw new import_shared7.SpotPatchError(import_shared7.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared14.SpotPatchError(import_shared14.ERROR_CODES.INVALID_REQUEST);
   }
-  const parsed = import_shared7.agentJobCreateRequestSchema.safeParse(
+  const parsed = import_shared14.agentJobCreateRequestSchema.safeParse(
     await readJsonRequestBody(request, MAX_AGENT_REQUEST_BODY_BYTES)
   );
   if (!parsed.success) {
-    throw new import_shared7.SpotPatchError(import_shared7.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared14.SpotPatchError(import_shared14.ERROR_CODES.INVALID_REQUEST);
   }
   const authorizedRequest = await authorizeAgentJobRequest({
     request: parsed.data,
@@ -2077,13 +3193,13 @@ async function handleCreateJob(request, response, options, writeSuccess) {
 }
 async function handleWorkspaceHealth(request, response, options, writeSuccess) {
   if (request.method !== "POST") {
-    throw new import_shared7.SpotPatchError(import_shared7.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared14.SpotPatchError(import_shared14.ERROR_CODES.INVALID_REQUEST);
   }
-  const parsed = import_shared7.agentWorkspaceHealthRequestSchema.safeParse(
+  const parsed = import_shared14.agentWorkspaceHealthRequestSchema.safeParse(
     await readJsonRequestBody(request)
   );
   if (!parsed.success) {
-    throw new import_shared7.SpotPatchError(import_shared7.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared14.SpotPatchError(import_shared14.ERROR_CODES.INVALID_REQUEST);
   }
   const controller = new AbortController();
   const abort = () => {
@@ -2100,13 +3216,13 @@ async function handleWorkspaceHealth(request, response, options, writeSuccess) {
 async function handleJobAction(request, response, options, route, writeSuccess) {
   const manager = requireAgentManager(options);
   if (request.method !== "POST") {
-    throw new import_shared7.SpotPatchError(import_shared7.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared14.SpotPatchError(import_shared14.ERROR_CODES.INVALID_REQUEST);
   }
-  const parsed = import_shared7.agentJobActionRequestSchema.safeParse(
+  const parsed = import_shared14.agentJobActionRequestSchema.safeParse(
     await readJsonRequestBody(request)
   );
   if (!parsed.success) {
-    throw new import_shared7.SpotPatchError(import_shared7.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared14.SpotPatchError(import_shared14.ERROR_CODES.INVALID_REQUEST);
   }
   if (route.action === "events") {
     streamAgentJobEvents(response, manager, route.jobId);
@@ -2221,27 +3337,27 @@ function createEditorLauncher(dependencies = DEFAULT_DEPENDENCIES2) {
 var launchConfiguredEditor = createEditorLauncher();
 
 // src/server/data-flow-http.ts
-var import_node_crypto4 = require("crypto");
+var import_node_crypto9 = require("crypto");
 var import_analyzer = require("@spotpatch/analyzer");
-var import_shared8 = require("@spotpatch/shared");
+var import_shared15 = require("@spotpatch/shared");
 function envelopeBytes(report) {
   return Buffer.byteLength(JSON.stringify({ ok: true, data: report }), "utf8");
 }
 function limitDataFlowReportToBytes(report, maximumBytes) {
-  const structurallyLimited = (0, import_shared8.limitDataFlowReportCollections)(report);
+  const structurallyLimited = (0, import_shared15.limitDataFlowReportCollections)(report);
   if (envelopeBytes(structurallyLimited) <= maximumBytes) {
     return structurallyLimited;
   }
-  let limited = (0, import_shared8.limitDataFlowReportCollections)(structurallyLimited, {
+  let limited = (0, import_shared15.limitDataFlowReportCollections)(structurallyLimited, {
     forceTruncation: true,
     maximumDependencies: 0,
     truncatedBy: "bytes"
   });
   if (envelopeBytes(limited) > maximumBytes) {
-    throw new import_shared8.SpotPatchError(import_shared8.ERROR_CODES.INTERNAL_ERROR);
+    throw new import_shared15.SpotPatchError(import_shared15.ERROR_CODES.INTERNAL_ERROR);
   }
   for (let maximumDependencies = 1; maximumDependencies <= structurallyLimited.dependencies.length; maximumDependencies += 1) {
-    const candidate = (0, import_shared8.limitDataFlowReportCollections)(structurallyLimited, {
+    const candidate = (0, import_shared15.limitDataFlowReportCollections)(structurallyLimited, {
       forceTruncation: true,
       maximumDependencies,
       truncatedBy: "bytes"
@@ -2267,7 +3383,7 @@ async function analyzeTarget(request, analyzer, options) {
         request.componentSourceId
       );
       if (anchor?.sourceVersion !== request.sourceVersion) {
-        throw new import_shared8.SpotPatchError(import_shared8.ERROR_CODES.DATA_FLOW_SOURCE_STALE);
+        throw new import_shared15.SpotPatchError(import_shared15.ERROR_CODES.DATA_FLOW_SOURCE_STALE);
       }
       return anchor;
     }
@@ -2284,7 +3400,7 @@ async function analyzeTarget(request, analyzer, options) {
     column: resolvedRequest.column
   });
   if (resolvedRequest.sourceVersion !== void 0 && resolvedRequest.sourceVersion !== report.component.source.sourceVersion) {
-    throw new import_shared8.SpotPatchError(import_shared8.ERROR_CODES.DATA_FLOW_SOURCE_STALE);
+    throw new import_shared15.SpotPatchError(import_shared15.ERROR_CODES.DATA_FLOW_SOURCE_STALE);
   }
   return limitDataFlowReportToBytes(
     report,
@@ -2293,31 +3409,31 @@ async function analyzeTarget(request, analyzer, options) {
 }
 function requireAnalyzer(analyzer) {
   if (analyzer === void 0) {
-    throw new import_shared8.SpotPatchError(import_shared8.ERROR_CODES.DATA_FLOW_DISABLED);
+    throw new import_shared15.SpotPatchError(import_shared15.ERROR_CODES.DATA_FLOW_DISABLED);
   }
   return analyzer;
 }
 async function handleComponentDataFlowReport(request, analyzer, options) {
-  const parsed = import_shared8.dataFlowComponentReportRequestSchema.safeParse(
+  const parsed = import_shared15.dataFlowComponentReportRequestSchema.safeParse(
     await readJsonRequestBody(
       request,
       options.options.dataFlow.limits.protocolRequestMaxBytes
     )
   );
   if (!parsed.success) {
-    throw new import_shared8.SpotPatchError(import_shared8.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared15.SpotPatchError(import_shared15.ERROR_CODES.INVALID_REQUEST);
   }
   return analyzeTarget(parsed.data, requireAnalyzer(analyzer), options);
 }
 async function handlePageDataFlowReport(request, analyzer, options) {
-  const parsed = import_shared8.dataFlowPageReportRequestSchema.safeParse(
+  const parsed = import_shared15.dataFlowPageReportRequestSchema.safeParse(
     await readJsonRequestBody(
       request,
       options.options.dataFlow.limits.protocolRequestMaxBytes
     )
   );
   if (!parsed.success) {
-    throw new import_shared8.SpotPatchError(import_shared8.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared15.SpotPatchError(import_shared15.ERROR_CODES.INVALID_REQUEST);
   }
   const activeAnalyzer = requireAnalyzer(analyzer);
   const componentReports = await Promise.all(
@@ -2341,10 +3457,10 @@ async function handlePageDataFlowReport(request, analyzer, options) {
   const analyzedVersions = new Set(
     componentReports.flatMap((report2) => report2.baseline.analyzedSourceVersions)
   );
-  const reportId = `page_${(0, import_node_crypto4.createHash)("sha256").update(componentReports.map((report2) => report2.reportId).join("\0")).digest("base64url").slice(0, 22)}`;
+  const reportId = `page_${(0, import_node_crypto9.createHash)("sha256").update(componentReports.map((report2) => report2.reportId).join("\0")).digest("base64url").slice(0, 22)}`;
   const complete = componentReports.every((report2) => report2.completeness.complete);
   const report = Object.freeze({
-    schemaVersion: import_shared8.DATA_FLOW_SCHEMA_VERSION,
+    schemaVersion: import_shared15.DATA_FLOW_SCHEMA_VERSION,
     reportId,
     baseline: Object.freeze({
       registryEpoch: options.session.id,
@@ -2388,20 +3504,20 @@ async function handlePageDataFlowReport(request, analyzer, options) {
 }
 
 // src/server/request-security.ts
-var import_node_crypto5 = require("crypto");
+var import_node_crypto10 = require("crypto");
 var import_node_net = require("net");
-var import_shared9 = require("@spotpatch/shared");
+var import_shared16 = require("@spotpatch/shared");
 function getSingleHeader(request, name) {
   const value = request.headers[name.toLowerCase()];
   return Array.isArray(value) ? value[0] : value;
 }
-function tokensMatch(actual, expected) {
+function tokensMatch2(actual, expected) {
   if (actual === void 0) {
     return false;
   }
   const actualBytes = Buffer.from(actual);
   const expectedBytes = Buffer.from(expected);
-  return actualBytes.byteLength === expectedBytes.byteLength && (0, import_node_crypto5.timingSafeEqual)(actualBytes, expectedBytes);
+  return actualBytes.byteLength === expectedBytes.byteLength && (0, import_node_crypto10.timingSafeEqual)(actualBytes, expectedBytes);
 }
 function isLoopbackHostname(hostname) {
   const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
@@ -2435,32 +3551,32 @@ function parseOrigin(value) {
   }
 }
 function assertRequestAuthorized(request, options) {
-  const actualToken = getSingleHeader(request, import_shared9.SPOTPATCH_TOKEN_HEADER);
-  if (!tokensMatch(actualToken, options.sessionToken)) {
-    throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.INVALID_TOKEN);
+  const actualToken = getSingleHeader(request, import_shared16.SPOTPATCH_TOKEN_HEADER);
+  if (!tokensMatch2(actualToken, options.sessionToken)) {
+    throw new import_shared16.SpotPatchError(import_shared16.ERROR_CODES.INVALID_TOKEN);
   }
   const hostHeader = getSingleHeader(request, "host");
   const originHeader = getSingleHeader(request, "origin");
   const host = hostHeader === void 0 ? void 0 : parseHost(hostHeader);
   const origin = originHeader === void 0 ? void 0 : parseOrigin(originHeader);
   if (host === void 0 || origin === void 0) {
-    throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.ORIGIN_NOT_ALLOWED);
+    throw new import_shared16.SpotPatchError(import_shared16.ERROR_CODES.ORIGIN_NOT_ALLOWED);
   }
   const hostIsLoopback = isLoopbackHostname(host.hostname);
   const originIsLoopback = isLoopbackHostname(origin.hostname);
   if (!options.allowLan) {
     if (!hostIsLoopback || !originIsLoopback) {
-      throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.ORIGIN_NOT_ALLOWED);
+      throw new import_shared16.SpotPatchError(import_shared16.ERROR_CODES.ORIGIN_NOT_ALLOWED);
     }
     return;
   }
   if (!originIsLoopback && origin.host.toLowerCase() !== host.host.toLowerCase()) {
-    throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.ORIGIN_NOT_ALLOWED);
+    throw new import_shared16.SpotPatchError(import_shared16.ERROR_CODES.ORIGIN_NOT_ALLOWED);
   }
 }
 
 // src/server/runtime-bootstrap.ts
-var import_shared10 = require("@spotpatch/shared");
+var import_shared17 = require("@spotpatch/shared");
 function getSingleHeader2(request, name) {
   const value = request.headers[name.toLowerCase()];
   return Array.isArray(value) ? value[0] : value;
@@ -2475,7 +3591,7 @@ function resolveRuntimeBootstrapOptions(options) {
   if (expectedOrigin.origin !== options.expectedOrigin || expectedOrigin.protocol !== "http:" || !isLoopbackHostname(expectedOrigin.hostname)) {
     throw new TypeError("The SpotPatch bootstrap origin must be a loopback origin.");
   }
-  const parsedConfig = import_shared10.runtimeConfigSchema.safeParse(options.runtimeConfig);
+  const parsedConfig = import_shared17.runtimeConfigSchema.safeParse(options.runtimeConfig);
   if (!parsedConfig.success) {
     throw new TypeError("The SpotPatch Runtime configuration is invalid.");
   }
@@ -2487,7 +3603,7 @@ function resolveRuntimeBootstrapOptions(options) {
 function assertRuntimeBootstrapRequest(request, expectedOrigin) {
   const contentType = getSingleHeader2(request, "content-type")?.split(";", 1)[0]?.trim().toLowerCase();
   if (request.method !== "POST" || contentType !== "application/json") {
-    throw new import_shared10.SpotPatchError(import_shared10.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared17.SpotPatchError(import_shared17.ERROR_CODES.INVALID_REQUEST);
   }
   const host = getSingleHeader2(request, "host");
   let hostIsLoopback = false;
@@ -2499,112 +3615,148 @@ function assertRuntimeBootstrapRequest(request, expectedOrigin) {
     }
   }
   if (!hostIsLoopback || getSingleHeader2(request, "origin") !== expectedOrigin || getSingleHeader2(request, "sec-fetch-site") !== "same-origin") {
-    throw new import_shared10.SpotPatchError(import_shared10.ERROR_CODES.ORIGIN_NOT_ALLOWED);
+    throw new import_shared17.SpotPatchError(import_shared17.ERROR_CODES.ORIGIN_NOT_ALLOWED);
   }
 }
 async function readRuntimeBootstrap(request, options) {
   assertRuntimeBootstrapRequest(request, options.expectedOrigin);
-  const parsedBody = import_shared10.runtimeBootstrapRequestSchema.safeParse(
+  const parsedBody = import_shared17.runtimeBootstrapRequestSchema.safeParse(
     await readJsonRequestBody(request)
   );
   if (!parsedBody.success) {
-    throw new import_shared10.SpotPatchError(import_shared10.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared17.SpotPatchError(import_shared17.ERROR_CODES.INVALID_REQUEST);
   }
   return options.runtimeConfig;
 }
 
 // src/server/middleware.ts
 var STATUS_BY_ERROR = Object.freeze({
-  [import_shared11.ERROR_CODES.INVALID_REQUEST]: 400,
-  [import_shared11.ERROR_CODES.INVALID_TOKEN]: 401,
-  [import_shared11.ERROR_CODES.ORIGIN_NOT_ALLOWED]: 403,
-  [import_shared11.ERROR_CODES.SOURCE_NOT_FOUND]: 404,
-  [import_shared11.ERROR_CODES.SOURCE_OUTSIDE_ROOT]: 403,
-  [import_shared11.ERROR_CODES.SOURCE_TOO_LARGE]: 413,
-  [import_shared11.ERROR_CODES.EDITOR_OPEN_FAILED]: 500,
-  [import_shared11.ERROR_CODES.DATA_FLOW_DISABLED]: 404,
-  [import_shared11.ERROR_CODES.DATA_FLOW_SOURCE_STALE]: 409,
-  [import_shared11.ERROR_CODES.DATA_FLOW_ANALYSIS_CANCELLED]: 409,
-  [import_shared11.ERROR_CODES.AI_DISABLED]: 404,
-  [import_shared11.ERROR_CODES.PROVIDER_NOT_CONFIGURED]: 503,
-  [import_shared11.ERROR_CODES.PROVIDER_AUTH_FAILED]: 502,
-  [import_shared11.ERROR_CODES.PROVIDER_PROTOCOL_UNSUPPORTED]: 502,
-  [import_shared11.ERROR_CODES.MODEL_NOT_ALLOWED]: 400,
-  [import_shared11.ERROR_CODES.MODEL_TOOL_CALL_UNSUPPORTED]: 422,
-  [import_shared11.ERROR_CODES.PROVIDER_RATE_LIMITED]: 429,
-  [import_shared11.ERROR_CODES.AGENT_BUSY]: 409,
-  [import_shared11.ERROR_CODES.AGENT_LIMIT_EXCEEDED]: 413,
-  [import_shared11.ERROR_CODES.AGENT_CANCELLED]: 409,
-  [import_shared11.ERROR_CODES.WORKTREE_DIRTY]: 409,
-  [import_shared11.ERROR_CODES.WORKTREE_NOT_REPOSITORY]: 409,
-  [import_shared11.ERROR_CODES.WORKTREE_OPERATION_IN_PROGRESS]: 409,
-  [import_shared11.ERROR_CODES.WORKTREE_CONFLICTED]: 409,
-  [import_shared11.ERROR_CODES.WORKTREE_LOCAL_CHANGES_TOO_LARGE]: 413,
-  [import_shared11.ERROR_CODES.WORKTREE_UNTRACKED_UNSUPPORTED]: 409,
-  [import_shared11.ERROR_CODES.WORKTREE_LOCAL_CHANGES_UNSUPPORTED]: 409,
-  [import_shared11.ERROR_CODES.TOOL_DENIED]: 403,
-  [import_shared11.ERROR_CODES.TOOL_INPUT_INVALID]: 422,
-  [import_shared11.ERROR_CODES.TOOL_ARGUMENTS_INVALID]: 422,
-  [import_shared11.ERROR_CODES.TOOL_CALL_ID_CONFLICT]: 422,
-  [import_shared11.ERROR_CODES.TOOL_PATH_DENIED]: 403,
-  [import_shared11.ERROR_CODES.PATCH_REJECTED]: 422,
-  [import_shared11.ERROR_CODES.VALIDATION_FAILED]: 422,
-  [import_shared11.ERROR_CODES.APPLY_CONFLICT]: 409,
-  [import_shared11.ERROR_CODES.INTERNAL_ERROR]: 500
+  [import_shared18.ERROR_CODES.INVALID_REQUEST]: 400,
+  [import_shared18.ERROR_CODES.INVALID_TOKEN]: 401,
+  [import_shared18.ERROR_CODES.ORIGIN_NOT_ALLOWED]: 403,
+  [import_shared18.ERROR_CODES.SOURCE_NOT_FOUND]: 404,
+  [import_shared18.ERROR_CODES.SOURCE_OUTSIDE_ROOT]: 403,
+  [import_shared18.ERROR_CODES.SOURCE_TOO_LARGE]: 413,
+  [import_shared18.ERROR_CODES.EDITOR_OPEN_FAILED]: 500,
+  [import_shared18.ERROR_CODES.DATA_FLOW_DISABLED]: 404,
+  [import_shared18.ERROR_CODES.DATA_FLOW_SOURCE_STALE]: 409,
+  [import_shared18.ERROR_CODES.DATA_FLOW_ANALYSIS_CANCELLED]: 409,
+  [import_shared18.ERROR_CODES.AI_DISABLED]: 404,
+  [import_shared18.ERROR_CODES.PROVIDER_NOT_CONFIGURED]: 503,
+  [import_shared18.ERROR_CODES.PROVIDER_AUTH_FAILED]: 502,
+  [import_shared18.ERROR_CODES.PROVIDER_PROTOCOL_UNSUPPORTED]: 502,
+  [import_shared18.ERROR_CODES.MODEL_NOT_ALLOWED]: 400,
+  [import_shared18.ERROR_CODES.MODEL_TOOL_CALL_UNSUPPORTED]: 422,
+  [import_shared18.ERROR_CODES.PROVIDER_RATE_LIMITED]: 429,
+  [import_shared18.ERROR_CODES.AGENT_BUSY]: 409,
+  [import_shared18.ERROR_CODES.AGENT_LIMIT_EXCEEDED]: 413,
+  [import_shared18.ERROR_CODES.AGENT_CANCELLED]: 409,
+  [import_shared18.ERROR_CODES.EXTERNAL_HANDOFF_DISABLED]: 404,
+  [import_shared18.ERROR_CODES.EXTERNAL_HANDOFF_UNAVAILABLE]: 503,
+  [import_shared18.ERROR_CODES.HANDOFF_VALIDATION_FAILED]: 422,
+  [import_shared18.ERROR_CODES.HANDOFF_SOURCE_STALE]: 409,
+  [import_shared18.ERROR_CODES.HANDOFF_NOT_FOUND]: 404,
+  [import_shared18.ERROR_CODES.HANDOFF_EXPIRED]: 410,
+  [import_shared18.ERROR_CODES.HANDOFF_CURSOR_INVALID]: 409,
+  [import_shared18.ERROR_CODES.HANDOFF_RESPONSE_TOO_LARGE]: 413,
+  [import_shared18.ERROR_CODES.BRIDGE_UNAUTHORIZED]: 401,
+  [import_shared18.ERROR_CODES.BRIDGE_PROTOCOL_MISMATCH]: 409,
+  [import_shared18.ERROR_CODES.BRIDGE_BUSY]: 429,
+  [import_shared18.ERROR_CODES.EXTERNAL_AGENT_BUSY]: 409,
+  [import_shared18.ERROR_CODES.ACTIVE_ADAPTER_CONFLICT]: 409,
+  [import_shared18.ERROR_CODES.ACTIVE_ADAPTER_LEASE_INVALID]: 409,
+  [import_shared18.ERROR_CODES.ACTIVE_DISPATCH_INVALID]: 409,
+  [import_shared18.ERROR_CODES.SESSION_NOT_FOUND]: 404,
+  [import_shared18.ERROR_CODES.SESSION_AMBIGUOUS]: 409,
+  [import_shared18.ERROR_CODES.SESSION_CLOSED]: 410,
+  [import_shared18.ERROR_CODES.WORKTREE_DIRTY]: 409,
+  [import_shared18.ERROR_CODES.WORKTREE_NOT_REPOSITORY]: 409,
+  [import_shared18.ERROR_CODES.WORKTREE_OPERATION_IN_PROGRESS]: 409,
+  [import_shared18.ERROR_CODES.WORKTREE_CONFLICTED]: 409,
+  [import_shared18.ERROR_CODES.WORKTREE_LOCAL_CHANGES_TOO_LARGE]: 413,
+  [import_shared18.ERROR_CODES.WORKTREE_UNTRACKED_UNSUPPORTED]: 409,
+  [import_shared18.ERROR_CODES.WORKTREE_LOCAL_CHANGES_UNSUPPORTED]: 409,
+  [import_shared18.ERROR_CODES.TOOL_DENIED]: 403,
+  [import_shared18.ERROR_CODES.TOOL_INPUT_INVALID]: 422,
+  [import_shared18.ERROR_CODES.TOOL_ARGUMENTS_INVALID]: 422,
+  [import_shared18.ERROR_CODES.TOOL_CALL_ID_CONFLICT]: 422,
+  [import_shared18.ERROR_CODES.TOOL_PATH_DENIED]: 403,
+  [import_shared18.ERROR_CODES.PATCH_REJECTED]: 422,
+  [import_shared18.ERROR_CODES.VALIDATION_FAILED]: 422,
+  [import_shared18.ERROR_CODES.APPLY_CONFLICT]: 409,
+  [import_shared18.ERROR_CODES.INTERNAL_ERROR]: 500
 });
 var PUBLIC_MESSAGES = Object.freeze({
-  [import_shared11.ERROR_CODES.INVALID_REQUEST]: "The request is invalid.",
-  [import_shared11.ERROR_CODES.INVALID_TOKEN]: "The session token is invalid.",
-  [import_shared11.ERROR_CODES.ORIGIN_NOT_ALLOWED]: "The request origin is not allowed.",
-  [import_shared11.ERROR_CODES.SOURCE_NOT_FOUND]: "The source file is unavailable.",
-  [import_shared11.ERROR_CODES.SOURCE_OUTSIDE_ROOT]: "The source file is outside the project root.",
-  [import_shared11.ERROR_CODES.SOURCE_TOO_LARGE]: "The source file exceeds the size limit.",
-  [import_shared11.ERROR_CODES.EDITOR_OPEN_FAILED]: "The editor request could not be started.",
-  [import_shared11.ERROR_CODES.DATA_FLOW_DISABLED]: "Component data-flow analysis is not enabled.",
-  [import_shared11.ERROR_CODES.DATA_FLOW_SOURCE_STALE]: "The selected source version is stale.",
-  [import_shared11.ERROR_CODES.DATA_FLOW_ANALYSIS_CANCELLED]: "The data-flow analysis was cancelled.",
-  [import_shared11.ERROR_CODES.AI_DISABLED]: "AI execution is not enabled.",
-  [import_shared11.ERROR_CODES.PROVIDER_NOT_CONFIGURED]: "The AI provider is unavailable.",
-  [import_shared11.ERROR_CODES.PROVIDER_AUTH_FAILED]: "The AI provider rejected authentication.",
-  [import_shared11.ERROR_CODES.PROVIDER_PROTOCOL_UNSUPPORTED]: "The AI provider protocol is unsupported.",
-  [import_shared11.ERROR_CODES.MODEL_NOT_ALLOWED]: "The selected model is not allowed.",
-  [import_shared11.ERROR_CODES.MODEL_TOOL_CALL_UNSUPPORTED]: "The selected model cannot run SpotPatch tools.",
-  [import_shared11.ERROR_CODES.PROVIDER_RATE_LIMITED]: "The AI provider is rate limited.",
-  [import_shared11.ERROR_CODES.AGENT_BUSY]: "Another Agent job is already running.",
-  [import_shared11.ERROR_CODES.AGENT_LIMIT_EXCEEDED]: "The Agent job exceeded a safety limit.",
-  [import_shared11.ERROR_CODES.AGENT_CANCELLED]: "The Agent job was cancelled.",
-  [import_shared11.ERROR_CODES.WORKTREE_DIRTY]: "Local changes require explicit inclusion consent.",
-  [import_shared11.ERROR_CODES.WORKTREE_NOT_REPOSITORY]: "The project root is not a Git repository.",
-  [import_shared11.ERROR_CODES.WORKTREE_OPERATION_IN_PROGRESS]: "A Git operation is currently in progress.",
-  [import_shared11.ERROR_CODES.WORKTREE_CONFLICTED]: "The local workspace contains unresolved merge conflicts.",
-  [import_shared11.ERROR_CODES.WORKTREE_LOCAL_CHANGES_TOO_LARGE]: "The local workspace exceeds the safe isolation size limit.",
-  [import_shared11.ERROR_CODES.WORKTREE_UNTRACKED_UNSUPPORTED]: "An untracked path cannot be isolated safely.",
-  [import_shared11.ERROR_CODES.WORKTREE_LOCAL_CHANGES_UNSUPPORTED]: "The local workspace state cannot be isolated safely.",
-  [import_shared11.ERROR_CODES.TOOL_DENIED]: "The Agent tool request was denied.",
-  [import_shared11.ERROR_CODES.TOOL_INPUT_INVALID]: "The Agent tool input was invalid.",
-  [import_shared11.ERROR_CODES.TOOL_ARGUMENTS_INVALID]: "The Agent tool arguments are invalid.",
-  [import_shared11.ERROR_CODES.TOOL_CALL_ID_CONFLICT]: "A tool call ID conflicts within one Agent turn.",
-  [import_shared11.ERROR_CODES.TOOL_PATH_DENIED]: "The Agent tool path was denied.",
-  [import_shared11.ERROR_CODES.PATCH_REJECTED]: "The proposed patch was rejected.",
-  [import_shared11.ERROR_CODES.VALIDATION_FAILED]: "The proposed change failed validation.",
-  [import_shared11.ERROR_CODES.APPLY_CONFLICT]: "The change conflicts with the current worktree.",
-  [import_shared11.ERROR_CODES.INTERNAL_ERROR]: "The request could not be completed."
+  [import_shared18.ERROR_CODES.INVALID_REQUEST]: "The request is invalid.",
+  [import_shared18.ERROR_CODES.INVALID_TOKEN]: "The session token is invalid.",
+  [import_shared18.ERROR_CODES.ORIGIN_NOT_ALLOWED]: "The request origin is not allowed.",
+  [import_shared18.ERROR_CODES.SOURCE_NOT_FOUND]: "The source file is unavailable.",
+  [import_shared18.ERROR_CODES.SOURCE_OUTSIDE_ROOT]: "The source file is outside the project root.",
+  [import_shared18.ERROR_CODES.SOURCE_TOO_LARGE]: "The source file exceeds the size limit.",
+  [import_shared18.ERROR_CODES.EDITOR_OPEN_FAILED]: "The editor request could not be started.",
+  [import_shared18.ERROR_CODES.DATA_FLOW_DISABLED]: "Component data-flow analysis is not enabled.",
+  [import_shared18.ERROR_CODES.DATA_FLOW_SOURCE_STALE]: "The selected source version is stale.",
+  [import_shared18.ERROR_CODES.DATA_FLOW_ANALYSIS_CANCELLED]: "The data-flow analysis was cancelled.",
+  [import_shared18.ERROR_CODES.AI_DISABLED]: "AI execution is not enabled.",
+  [import_shared18.ERROR_CODES.PROVIDER_NOT_CONFIGURED]: "The AI provider is unavailable.",
+  [import_shared18.ERROR_CODES.PROVIDER_AUTH_FAILED]: "The AI provider rejected authentication.",
+  [import_shared18.ERROR_CODES.PROVIDER_PROTOCOL_UNSUPPORTED]: "The AI provider protocol is unsupported.",
+  [import_shared18.ERROR_CODES.MODEL_NOT_ALLOWED]: "The selected model is not allowed.",
+  [import_shared18.ERROR_CODES.MODEL_TOOL_CALL_UNSUPPORTED]: "The selected model cannot run SpotPatch tools.",
+  [import_shared18.ERROR_CODES.PROVIDER_RATE_LIMITED]: "The AI provider is rate limited.",
+  [import_shared18.ERROR_CODES.AGENT_BUSY]: "Another Agent job is already running.",
+  [import_shared18.ERROR_CODES.AGENT_LIMIT_EXCEEDED]: "The Agent job exceeded a safety limit.",
+  [import_shared18.ERROR_CODES.AGENT_CANCELLED]: "The Agent job was cancelled.",
+  [import_shared18.ERROR_CODES.EXTERNAL_HANDOFF_DISABLED]: "External Agent handoff is not enabled.",
+  [import_shared18.ERROR_CODES.EXTERNAL_HANDOFF_UNAVAILABLE]: "External Agent handoff is temporarily unavailable.",
+  [import_shared18.ERROR_CODES.HANDOFF_VALIDATION_FAILED]: "The handoff content is invalid.",
+  [import_shared18.ERROR_CODES.HANDOFF_SOURCE_STALE]: "The selected source is stale.",
+  [import_shared18.ERROR_CODES.HANDOFF_NOT_FOUND]: "No current handoff is available.",
+  [import_shared18.ERROR_CODES.HANDOFF_EXPIRED]: "The handoff has expired.",
+  [import_shared18.ERROR_CODES.HANDOFF_CURSOR_INVALID]: "The handoff cursor is invalid.",
+  [import_shared18.ERROR_CODES.HANDOFF_RESPONSE_TOO_LARGE]: "The handoff exceeds the size limit.",
+  [import_shared18.ERROR_CODES.BRIDGE_UNAUTHORIZED]: "The local bridge request is unauthorized.",
+  [import_shared18.ERROR_CODES.BRIDGE_PROTOCOL_MISMATCH]: "The local bridge protocol is incompatible.",
+  [import_shared18.ERROR_CODES.BRIDGE_BUSY]: "The local bridge is busy.",
+  [import_shared18.ERROR_CODES.EXTERNAL_AGENT_BUSY]: "The connected external Agent is busy.",
+  [import_shared18.ERROR_CODES.ACTIVE_ADAPTER_CONFLICT]: "Another active Agent adapter is connected.",
+  [import_shared18.ERROR_CODES.ACTIVE_ADAPTER_LEASE_INVALID]: "The active Agent adapter lease is invalid.",
+  [import_shared18.ERROR_CODES.ACTIVE_DISPATCH_INVALID]: "The active Agent dispatch transition is invalid.",
+  [import_shared18.ERROR_CODES.SESSION_NOT_FOUND]: "No active SpotPatch session was found.",
+  [import_shared18.ERROR_CODES.SESSION_AMBIGUOUS]: "More than one SpotPatch session matches.",
+  [import_shared18.ERROR_CODES.SESSION_CLOSED]: "The SpotPatch session has closed.",
+  [import_shared18.ERROR_CODES.WORKTREE_DIRTY]: "Local changes require explicit inclusion consent.",
+  [import_shared18.ERROR_CODES.WORKTREE_NOT_REPOSITORY]: "The project root is not a Git repository.",
+  [import_shared18.ERROR_CODES.WORKTREE_OPERATION_IN_PROGRESS]: "A Git operation is currently in progress.",
+  [import_shared18.ERROR_CODES.WORKTREE_CONFLICTED]: "The local workspace contains unresolved merge conflicts.",
+  [import_shared18.ERROR_CODES.WORKTREE_LOCAL_CHANGES_TOO_LARGE]: "The local workspace exceeds the safe isolation size limit.",
+  [import_shared18.ERROR_CODES.WORKTREE_UNTRACKED_UNSUPPORTED]: "An untracked path cannot be isolated safely.",
+  [import_shared18.ERROR_CODES.WORKTREE_LOCAL_CHANGES_UNSUPPORTED]: "The local workspace state cannot be isolated safely.",
+  [import_shared18.ERROR_CODES.TOOL_DENIED]: "The Agent tool request was denied.",
+  [import_shared18.ERROR_CODES.TOOL_INPUT_INVALID]: "The Agent tool input was invalid.",
+  [import_shared18.ERROR_CODES.TOOL_ARGUMENTS_INVALID]: "The Agent tool arguments are invalid.",
+  [import_shared18.ERROR_CODES.TOOL_CALL_ID_CONFLICT]: "A tool call ID conflicts within one Agent turn.",
+  [import_shared18.ERROR_CODES.TOOL_PATH_DENIED]: "The Agent tool path was denied.",
+  [import_shared18.ERROR_CODES.PATCH_REJECTED]: "The proposed patch was rejected.",
+  [import_shared18.ERROR_CODES.VALIDATION_FAILED]: "The proposed change failed validation.",
+  [import_shared18.ERROR_CODES.APPLY_CONFLICT]: "The change conflicts with the current worktree.",
+  [import_shared18.ERROR_CODES.INTERNAL_ERROR]: "The request could not be completed."
 });
-function writeJson(response, status, payload) {
+function writeJson2(response, status, payload) {
   response.statusCode = status;
   response.setHeader("Cache-Control", "no-store");
   response.setHeader("Content-Type", "application/json; charset=utf-8");
   response.end(JSON.stringify(payload));
 }
 function asSpotPatchError(error) {
-  return error instanceof import_shared11.SpotPatchError ? error : new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INTERNAL_ERROR, void 0, { cause: error });
+  return error instanceof import_shared18.SpotPatchError ? error : new import_shared18.SpotPatchError(import_shared18.ERROR_CODES.INTERNAL_ERROR, void 0, { cause: error });
 }
 function writeError(response, error, logger) {
   const normalized = asSpotPatchError(error);
-  if (normalized.code === import_shared11.ERROR_CODES.INTERNAL_ERROR) {
+  if (normalized.code === import_shared18.ERROR_CODES.INTERNAL_ERROR) {
     logger?.warn("[spotpatch:server] Internal request failure.");
   }
-  writeJson(response, STATUS_BY_ERROR[normalized.code], {
+  writeJson2(response, STATUS_BY_ERROR[normalized.code], {
     ok: false,
     error: {
       code: normalized.code,
@@ -2620,11 +3772,11 @@ function requestPath(request) {
   }
 }
 async function handleSourceContext(request, options) {
-  const parsed = import_shared11.sourceContextRequestSchema.safeParse(
+  const parsed = import_shared18.sourceContextRequestSchema.safeParse(
     await readJsonRequestBody(request)
   );
   if (!parsed.success) {
-    throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared18.SpotPatchError(import_shared18.ERROR_CODES.INVALID_REQUEST);
   }
   return readSourceContext({
     request: parsed.data,
@@ -2635,9 +3787,9 @@ async function handleSourceContext(request, options) {
   });
 }
 async function handleOpenEditor(request, options) {
-  const parsed = import_shared11.openEditorRequestSchema.safeParse(await readJsonRequestBody(request));
+  const parsed = import_shared18.openEditorRequestSchema.safeParse(await readJsonRequestBody(request));
   if (!parsed.success) {
-    throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
+    throw new import_shared18.SpotPatchError(import_shared18.ERROR_CODES.INVALID_REQUEST);
   }
   const body = parsed.data;
   const sourcePath = await resolveSourceFile({
@@ -2654,7 +3806,7 @@ async function handleOpenEditor(request, options) {
     options.logger?.warn(
       `[spotpatch:server] ${options.options.editor === "auto" ? "The detected editor" : options.options.editor} rejected an editor request.`
     );
-    throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.EDITOR_OPEN_FAILED, void 0, {
+    throw new import_shared18.SpotPatchError(import_shared18.ERROR_CODES.EDITOR_OPEN_FAILED, void 0, {
       cause: error
     });
   }
@@ -2663,63 +3815,81 @@ function createSpotPatchMiddleware(options) {
   const bootstrap = options.bootstrap === void 0 ? void 0 : resolveRuntimeBootstrapOptions(options.bootstrap);
   const dataFlowAnalyzer = createDataFlowAnalyzer(options);
   return (request, response, next) => {
-    const path8 = requestPath(request);
-    const agentRoute = matchAgentRequestPath(path8);
-    if (path8 !== import_shared11.SPOTPATCH_ENDPOINTS.sourceContext && path8 !== import_shared11.SPOTPATCH_ENDPOINTS.openEditor && path8 !== import_shared11.SPOTPATCH_ENDPOINTS.dataFlowComponentReport && path8 !== import_shared11.SPOTPATCH_ENDPOINTS.dataFlowPageReport && agentRoute === void 0 && !path8.startsWith(`${import_shared11.SPOTPATCH_API_BASE}/`)) {
+    const path9 = requestPath(request);
+    const agentRoute = matchAgentRequestPath(path9);
+    const externalHandoffRoute = matchExternalHandoffBrowserPath(path9);
+    if (path9 !== import_shared18.SPOTPATCH_ENDPOINTS.sourceContext && path9 !== import_shared18.SPOTPATCH_ENDPOINTS.openEditor && path9 !== import_shared18.SPOTPATCH_ENDPOINTS.dataFlowComponentReport && path9 !== import_shared18.SPOTPATCH_ENDPOINTS.dataFlowPageReport && agentRoute === void 0 && externalHandoffRoute === void 0 && !path9.startsWith(`${import_shared18.SPOTPATCH_API_BASE}/`)) {
       next();
       return;
     }
     const handle = async () => {
-      if (path8 === import_shared11.SPOTPATCH_ENDPOINTS.bootstrap && bootstrap !== void 0) {
+      if (path9 === import_shared18.SPOTPATCH_ENDPOINTS.bootstrap && bootstrap !== void 0) {
         const data = await readRuntimeBootstrap(
           request,
           bootstrap
         );
-        writeJson(response, 200, { ok: true, data });
+        writeJson2(response, 200, { ok: true, data });
         return;
       }
       assertRequestAuthorized(request, {
         allowLan: options.options.allowLan,
         sessionToken: options.session.token
       });
-      if (path8 === import_shared11.SPOTPATCH_ENDPOINTS.sourceContext) {
+      if (path9 === import_shared18.SPOTPATCH_ENDPOINTS.sourceContext) {
         if (request.method !== "POST") {
-          throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
+          throw new import_shared18.SpotPatchError(import_shared18.ERROR_CODES.INVALID_REQUEST);
         }
         const data = await handleSourceContext(request, options);
-        writeJson(response, 200, { ok: true, data });
+        writeJson2(response, 200, { ok: true, data });
         return;
       }
-      if (path8 === import_shared11.SPOTPATCH_ENDPOINTS.openEditor) {
+      if (path9 === import_shared18.SPOTPATCH_ENDPOINTS.openEditor) {
         if (request.method !== "POST") {
-          throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
+          throw new import_shared18.SpotPatchError(import_shared18.ERROR_CODES.INVALID_REQUEST);
         }
         const data = await handleOpenEditor(request, options);
-        writeJson(response, 200, { ok: true, data });
+        writeJson2(response, 200, { ok: true, data });
         return;
       }
-      if (path8 === import_shared11.SPOTPATCH_ENDPOINTS.dataFlowComponentReport) {
+      if (path9 === import_shared18.SPOTPATCH_ENDPOINTS.dataFlowComponentReport) {
         if (request.method !== "POST") {
-          throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
+          throw new import_shared18.SpotPatchError(import_shared18.ERROR_CODES.INVALID_REQUEST);
         }
         const data = await handleComponentDataFlowReport(
           request,
           dataFlowAnalyzer,
           options
         );
-        writeJson(response, 200, { ok: true, data });
+        writeJson2(response, 200, { ok: true, data });
         return;
       }
-      if (path8 === import_shared11.SPOTPATCH_ENDPOINTS.dataFlowPageReport) {
+      if (path9 === import_shared18.SPOTPATCH_ENDPOINTS.dataFlowPageReport) {
         if (request.method !== "POST") {
-          throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
+          throw new import_shared18.SpotPatchError(import_shared18.ERROR_CODES.INVALID_REQUEST);
         }
         const data = await handlePageDataFlowReport(request, dataFlowAnalyzer, options);
-        writeJson(response, 200, { ok: true, data });
+        writeJson2(response, 200, { ok: true, data });
+        return;
+      }
+      if (externalHandoffRoute !== void 0) {
+        await handleExternalHandoffBrowserRequest(
+          request,
+          response,
+          externalHandoffRoute,
+          {
+            options: options.options,
+            registry: options.registry,
+            root: options.root,
+            ...options.externalHandoffService === void 0 ? {} : { service: options.externalHandoffService }
+          },
+          (target, status, data) => {
+            writeJson2(target, status, { ok: true, data });
+          }
+        );
         return;
       }
       if (agentRoute === void 0) {
-        throw new import_shared11.SpotPatchError(import_shared11.ERROR_CODES.INVALID_REQUEST);
+        throw new import_shared18.SpotPatchError(import_shared18.ERROR_CODES.INVALID_REQUEST);
       }
       await handleAgentRequest(
         request,
@@ -2727,7 +3897,7 @@ function createSpotPatchMiddleware(options) {
         options,
         agentRoute,
         (target, status, data) => {
-          writeJson(target, status, { ok: true, data });
+          writeJson2(target, status, { ok: true, data });
         }
       );
     };
@@ -2738,9 +3908,9 @@ function createSpotPatchMiddleware(options) {
 }
 
 // src/server/source-registration.ts
-var import_node_crypto6 = require("crypto");
-var import_promises6 = require("fs/promises");
-var import_node_path7 = __toESM(require("path"), 1);
+var import_node_crypto11 = require("crypto");
+var import_promises7 = require("fs/promises");
+var import_node_path8 = __toESM(require("path"), 1);
 var import_compiler = require("@spotpatch/compiler");
 var import_zod2 = require("zod");
 var REGISTRATION_BODY_LIMIT_BYTES = 4096;
@@ -2761,16 +3931,16 @@ function identitiesMatch(actual, expected) {
   }
   const actualBytes = Buffer.from(actual);
   const expectedBytes = Buffer.from(expected);
-  return actualBytes.byteLength === expectedBytes.byteLength && (0, import_node_crypto6.timingSafeEqual)(actualBytes, expectedBytes);
+  return actualBytes.byteLength === expectedBytes.byteLength && (0, import_node_crypto11.timingSafeEqual)(actualBytes, expectedBytes);
 }
 function isWithinRoot(root, candidate) {
-  const relative = import_node_path7.default.relative(root, candidate);
-  return relative === "" || !relative.startsWith(`..${import_node_path7.default.sep}`) && relative !== ".." && !import_node_path7.default.isAbsolute(relative);
+  const relative = import_node_path8.default.relative(root, candidate);
+  return relative === "" || !relative.startsWith(`..${import_node_path8.default.sep}`) && relative !== ".." && !import_node_path8.default.isAbsolute(relative);
 }
 function hasForbiddenSegment(root, candidate) {
-  return import_node_path7.default.relative(root, candidate).split(import_node_path7.default.sep).some((segment) => FORBIDDEN_SOURCE_SEGMENTS.has(segment));
+  return import_node_path8.default.relative(root, candidate).split(import_node_path8.default.sep).some((segment) => FORBIDDEN_SOURCE_SEGMENTS.has(segment));
 }
-function writeJson2(response, statusCode, payload) {
+function writeJson3(response, statusCode, payload) {
   const body = JSON.stringify(payload);
   response.statusCode = statusCode;
   response.setHeader("Cache-Control", "no-store");
@@ -2790,15 +3960,15 @@ function requestComesFromLoopbackWorker(request) {
   }
 }
 async function resolveAuthorizedSource(root, requestedPath, shouldTransform) {
-  if (!import_node_path7.default.isAbsolute(requestedPath) || requestedPath.includes("\0")) {
+  if (!import_node_path8.default.isAbsolute(requestedPath) || requestedPath.includes("\0")) {
     return void 0;
   }
   try {
-    const sourceStat = await (0, import_promises6.lstat)(requestedPath);
+    const sourceStat = await (0, import_promises7.lstat)(requestedPath);
     if (!sourceStat.isFile() || sourceStat.isSymbolicLink()) {
       return void 0;
     }
-    const resolvedPath = await (0, import_promises6.realpath)(requestedPath);
+    const resolvedPath = await (0, import_promises7.realpath)(requestedPath);
     if (!isWithinRoot(root, resolvedPath) || hasForbiddenSegment(root, resolvedPath) || !shouldTransform(resolvedPath)) {
       return void 0;
     }
@@ -2811,7 +3981,7 @@ async function createSourceRegistrationService(input) {
   if (!REGISTRATION_IDENTITY_PATTERN.test(input.internalSecret) || !REGISTRATION_IDENTITY_PATTERN.test(input.registryEpoch)) {
     throw new TypeError("The source registration identity is invalid.");
   }
-  const root = await (0, import_promises6.realpath)(input.root);
+  const root = await (0, import_promises7.realpath)(input.root);
   const sourceFilter = (0, import_compiler.createSourceFilter)(root, input.options);
   const handler = (request, response) => {
     const handle = async () => {
@@ -2820,14 +3990,14 @@ async function createSourceRegistrationService(input) {
         getSingleHeader3(request, INTERNAL_SECRET_HEADER),
         input.internalSecret
       )) {
-        writeJson2(response, 403, { ok: false });
+        writeJson3(response, 403, { ok: false });
         return;
       }
       const parsed = registrationRequestSchema.safeParse(
         await readJsonRequestBody(request, REGISTRATION_BODY_LIMIT_BYTES)
       );
       if (!parsed.success || parsed.data.epoch !== input.registryEpoch) {
-        writeJson2(response, 400, { ok: false });
+        writeJson3(response, 400, { ok: false });
         return;
       }
       const sourcePath = await resolveAuthorizedSource(
@@ -2836,17 +4006,17 @@ async function createSourceRegistrationService(input) {
         (absolutePath) => sourceFilter.shouldTransform(absolutePath, "<")
       );
       if (sourcePath === void 0) {
-        writeJson2(response, 403, { ok: false });
+        writeJson3(response, 403, { ok: false });
         return;
       }
-      writeJson2(response, 200, {
+      writeJson3(response, 200, {
         epoch: input.registryEpoch,
         fileId: input.registry.register(sourcePath)
       });
     };
     void handle().catch(() => {
       if (!response.headersSent) {
-        writeJson2(response, 400, { ok: false });
+        writeJson3(response, 400, { ok: false });
       } else {
         response.destroy();
       }
@@ -2856,11 +4026,11 @@ async function createSourceRegistrationService(input) {
 }
 
 // src/session/session.ts
-var import_node_crypto7 = require("crypto");
+var import_node_crypto12 = require("crypto");
 function createSession() {
   return Object.freeze({
-    id: (0, import_node_crypto7.randomBytes)(16).toString("base64url"),
-    token: (0, import_node_crypto7.randomBytes)(16).toString("base64url")
+    id: (0, import_node_crypto12.randomBytes)(16).toString("base64url"),
+    token: (0, import_node_crypto12.randomBytes)(16).toString("base64url")
   });
 }
 
@@ -2873,6 +4043,7 @@ var OPTION_KEYS = Object.freeze([
   "dataFlow",
   "editor",
   "enabled",
+  "externalAgent",
   "exclude",
   "include",
   "locale",
@@ -2963,6 +4134,7 @@ function serializeResolvedSpotPatchOptions(options) {
     }) : false,
     editor: options.editor,
     enabled: options.enabled,
+    externalAgent: options.externalAgent.enabled,
     exclude: Object.freeze(options.exclude.map(serializeFilter)),
     include: Object.freeze(options.include.map(serializeFilter)),
     locale: options.locale,
@@ -3016,7 +4188,7 @@ function parseSerializedSpotPatchOptions(value) {
   if (!isRecord2(value) || !hasExactKeys(value, OPTION_KEYS)) {
     throw new TypeError("The SpotPatch options transport is invalid.");
   }
-  if (typeof value.enabled !== "boolean" || typeof value.redact !== "boolean" || typeof value.allowLan !== "boolean" || typeof value.debug !== "boolean" || typeof value.shortcut !== "string" || typeof value.maxTargets !== "number" || typeof value.editor !== "string" || typeof value.locale !== "string" || value.ai !== false && !isRecord2(value.ai)) {
+  if (typeof value.enabled !== "boolean" || typeof value.externalAgent !== "boolean" || typeof value.redact !== "boolean" || typeof value.allowLan !== "boolean" || typeof value.debug !== "boolean" || typeof value.shortcut !== "string" || typeof value.maxTargets !== "number" || typeof value.editor !== "string" || typeof value.locale !== "string" || value.ai !== false && !isRecord2(value.ai)) {
     throw new TypeError("The SpotPatch options transport is invalid.");
   }
   try {
@@ -3028,6 +4200,7 @@ function parseSerializedSpotPatchOptions(value) {
       dataFlow: parseDataFlow(value.dataFlow),
       editor: value.editor,
       enabled: value.enabled,
+      externalAgent: value.externalAgent,
       exclude: parseFilterList(value.exclude),
       include: parseFilterList(value.include),
       locale: value.locale,
@@ -3047,6 +4220,7 @@ function parseSerializedSpotPatchOptions(value) {
   DEFAULT_OPTIONS,
   applyIntegrationPlan,
   createAgentJobManager,
+  createExternalHandoffService,
   createIntegrationFileChange,
   createRuntimeAiConfig,
   createRuntimeDataFlowConfig,