@cursor/bdk 0.2.2 → 0.2.3

package/src/internal/hosted-delivery.ts

@@ -36,7 +36,8 @@ import {
   HOSTED_GUEST_RETRY_TERMINAL,
   HOSTED_GUEST_RETRY_TRANSIENT,
   HOSTED_MAX_CONSUMED_DELIVERY_IDS,
-  type HostedAdmission,
+  type HostedAdmissionInput,
+  type HostedAdmissionStart,
   type HostedGuestRetryDisposition,
   type HostedReminderFireDescriptorPayload,
   hostedFailureClassification,
@@ -74,7 +75,7 @@ import { type EngineSendOptions, HostedEnqueueNotActiveError } from "./session-e
 import type { SessionRunExecutionWrite } from "./session-run-log.js";
 
 type DispatchInput = {
-  delivery: HostedAdmission;
+  delivery: HostedAdmissionInput;
   definition: object;
   args: ChannelHandlerArgs;
 };
@@ -94,6 +95,13 @@ type AdmissionDispatch = {
 type ExecutionReply = {
   status: number;
   body: Record<string, unknown>;
+  serverTiming?: string;
+};
+
+type AdmissionOperation = {
+  execution: Promise<ExecutionReply>;
+  settledReply?: ExecutionReply;
+  expiresAt: number;
 };
 
 type HostedEnqueueOutcome = {
@@ -109,6 +117,29 @@ type ActiveOwnerContext = {
   enqueueResults: Map<string, Promise<HostedEnqueueOutcome>>;
 };
 
+async function responseToReply(response: Response): Promise<ExecutionReply> {
+  const value = (await response.json()) as unknown;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("Hosted delivery produced a non-object JSON response.");
+  }
+  return {
+    status: response.status,
+    body: value as Record<string, unknown>,
+    serverTiming: response.headers.get("server-timing") ?? undefined,
+  };
+}
+
+function responseFromReply(reply: ExecutionReply): Response {
+  return Response.json(reply.body, {
+    status: reply.status,
+    headers: reply.serverTiming === undefined ? undefined : { "server-timing": reply.serverTiming },
+  });
+}
+
+function isTransientRetryReply(reply: ExecutionReply): boolean {
+  return reply.body.retry === HOSTED_GUEST_RETRY_TRANSIENT;
+}
+
 /**
  * A second `send()` in one delivery is a deterministic authored bug — the
  * wire protocol carries exactly one pending send per delivery — so it must
@@ -137,6 +168,21 @@ function boundedMessage(text: string): string {
     : text;
 }
 
+/**
+ * A channel's non-OK dispatch response body is the only record of why the
+ * delivery was refused (e.g. an authored 400 with a validation message).
+ * Carry it, bounded, into the terminal channel_dispatch_failed so the
+ * control plane's failure log is diagnosable.
+ */
+async function channelDispatchDetail(response: Response): Promise<string | undefined> {
+  try {
+    const text = (await response.text()).trim();
+    return text === "" ? undefined : boundedMessage(text);
+  } catch {
+    return undefined;
+  }
+}
+
 function terminalHostedError(status: number, error: string, message?: string): Response {
   return hostedGuestErrorResponse({
     status,
@@ -250,7 +296,7 @@ async function dispatchHostedReminderAdmission(
       reason?: string;
     }>;
   },
-  delivery: HostedAdmission,
+  delivery: HostedAdmissionInput,
 ): Promise<Response> {
   const descriptor = parseHostedReminderFireDescriptorPayload(delivery.payload);
   if (descriptor !== undefined) {
@@ -364,6 +410,7 @@ async function runAdmission(
       response: terminalHostedError(
         dispatched.status >= 400 ? dispatched.status : 502,
         "channel_dispatch_failed",
+        await channelDispatchDetail(dispatched),
       ),
     };
   }
@@ -564,10 +611,14 @@ export function registerHostedDeliveryRoute(input: {
       deliveryId: string;
       sessionPublicId?: string;
       execution?: Promise<ExecutionReply>;
+      settledReply?: ExecutionReply;
     }
   >();
+  const admissions = new Map<string, AdmissionOperation>();
   const activeOwners = new Map<string, ActiveOwnerContext>();
   const pendingTtlMs = 10 * 60_000;
+  /** Keep an in-flight owner turn addressable for status polls. */
+  const ownerTurnPendingTtlMs = 12 * 60 * 60_000;
   const waitForNetwork = input.waitForGuestNetwork ?? (() => waitForGuestNetworkReady());
   const consumeBoundSecrets = input.consumeBoundSecrets ?? (() => consumeHostedBoundSecrets());
   /**
@@ -613,7 +664,81 @@ export function registerHostedDeliveryRoute(input: {
         pending.delete(token);
       }
     }
+    for (const [deliveryId, operation] of admissions) {
+      if (operation.expiresAt <= now) {
+        admissions.delete(deliveryId);
+      }
+    }
   };
+  const runAdmissionOperation = async (
+    delivery: HostedAdmissionStart,
+    definition: object | undefined,
+  ): Promise<ExecutionReply> =>
+    afterHostedWork(input.flushOtel, async () => {
+      const startedAt = performance.now();
+      let guestNetwork: GuestNetworkWaitStats | undefined;
+      const finish = (response: Response) =>
+        withServerTiming(response, performance.now() - startedAt, guestNetwork);
+      try {
+        const network = await finishNetworkWait("admission");
+        guestNetwork = network.timing;
+        if (network.response !== undefined) {
+          return await responseToReply(finish(network.response));
+        }
+        if (isHostedReminderAdmission(delivery)) {
+          return await responseToReply(
+            finish(await dispatchHostedReminderAdmission(input, delivery)),
+          );
+        }
+        if (definition === undefined) {
+          return await responseToReply(
+            finish(
+              terminalHostedError(
+                404,
+                "channel_not_found",
+                `No channel named "${delivery.channelId}" is mounted.`,
+              ),
+            ),
+          );
+        }
+        const admitted = await dispatchHostedAdmission({
+          delivery,
+          definition,
+          args: input.buildHandlerArgs(delivery.channelId),
+        });
+        if (admitted.pendingSend === undefined) {
+          return await responseToReply(finish(admitted.response));
+        }
+        pruneExpired();
+        const admissionToken = randomBytes(24).toString("hex");
+        pending.set(admissionToken, {
+          send: admitted.pendingSend,
+          channelKind: delivery.channelKind,
+          expiresAt: Date.now() + pendingTtlMs,
+          deliveryId: delivery.deliveryId,
+        });
+        return await responseToReply(
+          finish(
+            Response.json({
+              ok: true,
+              v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+              outcome: "send",
+              admissionToken,
+            }),
+          ),
+        );
+      } catch (error) {
+        return await responseToReply(
+          finish(
+            terminalHostedError(
+              503,
+              "internal_error",
+              boundedMessage(error instanceof Error ? error.message : String(error)),
+            ),
+          ),
+        );
+      }
+    });
 
   // Hosted callers reach this only through Anyrun's signed pod-port URL.
   // The marker is a second, route-specific fence distinct from channel auth.
@@ -634,9 +759,8 @@ export function registerHostedDeliveryRoute(input: {
     handler: async request =>
       afterHostedWork(input.flushOtel, async () => {
         const startedAt = performance.now();
-        let guestNetwork: GuestNetworkWaitStats | undefined;
         const finish = (response: Response) =>
-          withServerTiming(response, performance.now() - startedAt, guestNetwork);
+          withServerTiming(response, performance.now() - startedAt);
         const unconsumed = finishBoundSecrets();
         if (unconsumed !== undefined) {
           return finish(unconsumed);
@@ -661,20 +785,53 @@ export function registerHostedDeliveryRoute(input: {
             ),
           );
         }
+        pruneExpired();
+        const existing = admissions.get(delivery.deliveryId);
+        if (delivery.mode === "status") {
+          if (existing === undefined) {
+            return finish(
+              transientHostedError(
+                409,
+                "hosted_admission_unavailable",
+                "No hosted admission is in flight for this delivery.",
+              ),
+            );
+          }
+          return existing.settledReply === undefined
+            ? finish(
+                Response.json({
+                  ok: true,
+                  v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+                  outcome: "running",
+                }),
+              )
+            : responseFromReply(existing.settledReply);
+        }
+        if (existing !== undefined) {
+          if (existing.settledReply !== undefined && isTransientRetryReply(existing.settledReply)) {
+            admissions.delete(delivery.deliveryId);
+          } else {
+            return existing.settledReply === undefined
+              ? finish(
+                  Response.json({
+                    ok: true,
+                    v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+                    outcome: "started",
+                  }),
+                )
+              : responseFromReply(existing.settledReply);
+          }
+        }
+
         console.info(
           `[agent-sdk] hosted admission received deliveryId=${delivery.deliveryId} channelId=${delivery.channelId} channelKind=${delivery.channelKind} eventType=${delivery.eventType} sessionMode=${delivery.sessionMode} managedAutomation=${delivery.managedAutomation === undefined ? "<absent>" : `automationUuid=${delivery.managedAutomation.automationUuid} mcpServerNames=${String(delivery.managedAutomation.mcpServerNames.length)} slackChannels=${delivery.managedAutomation.slackChannels === undefined ? "<absent>" : JSON.stringify(delivery.managedAutomation.slackChannels)}`}`,
         );
         recordHostedManagedAutomation(delivery);
-        if (isHostedReminderAdmission(delivery)) {
-          const network = await finishNetworkWait("admission");
-          guestNetwork = network.timing;
-          if (network.response !== undefined) {
-            return finish(network.response);
-          }
-          return finish(await dispatchHostedReminderAdmission(input, delivery));
-        }
-        const channel = input.channels.find(candidate => candidate.id === delivery.channelId);
-        if (channel === undefined) {
+        const reminder = isHostedReminderAdmission(delivery);
+        const definition = reminder
+          ? undefined
+          : input.channels.find(candidate => candidate.id === delivery.channelId)?.definition;
+        if (!reminder && definition === undefined) {
           return finish(
             terminalHostedError(
               404,
@@ -683,33 +840,29 @@ export function registerHostedDeliveryRoute(input: {
             ),
           );
         }
-        const network = await finishNetworkWait("admission");
-        guestNetwork = network.timing;
-        if (network.response !== undefined) {
-          return finish(network.response);
-        }
-        const admitted = await dispatchHostedAdmission({
-          delivery,
-          definition: channel.definition,
-          args: input.buildHandlerArgs(delivery.channelId),
+        let operation: AdmissionOperation;
+        const execution = runAdmissionOperation(delivery, definition).then(reply => {
+          operation.settledReply = reply;
+          operation.expiresAt = Date.now() + pendingTtlMs;
+          return reply;
         });
-        if (admitted.pendingSend === undefined) {
-          return finish(admitted.response);
+        operation = {
+          execution,
+          expiresAt: Date.now() + ownerTurnPendingTtlMs,
+        };
+        admissions.set(delivery.deliveryId, operation);
+        const quickReply = await Promise.race([
+          execution,
+          new Promise<undefined>(resolve => setImmediate(() => resolve(undefined))),
+        ]);
+        if (quickReply !== undefined) {
+          return responseFromReply(quickReply);
         }
-        pruneExpired();
-        const admissionToken = randomBytes(24).toString("hex");
-        pending.set(admissionToken, {
-          send: admitted.pendingSend,
-          channelKind: delivery.channelKind,
-          expiresAt: Date.now() + pendingTtlMs,
-          deliveryId: delivery.deliveryId,
-        });
         return finish(
           Response.json({
             ok: true,
             v: HOSTED_DELIVERY_PROTOCOL_VERSION,
-            outcome: "send",
-            admissionToken,
+            outcome: "started",
           }),
         );
       }),
@@ -762,14 +915,58 @@ export function registerHostedDeliveryRoute(input: {
             ),
           );
         }
-        const network = await finishNetworkWait("execution");
-        guestNetwork = network.timing;
-        if (network.response !== undefined) {
-          return finish(network.response);
+
+        if (
+          execution.mode === "start" &&
+          admitted.settledReply !== undefined &&
+          isTransientRetryReply(admitted.settledReply)
+        ) {
+          delete admitted.settledReply;
+          delete admitted.execution;
         }
+
+        if (
+          execution.mode === "status" ||
+          (execution.mode === "start" && admitted.execution !== undefined)
+        ) {
+          if (admitted.settledReply !== undefined) {
+            return responseFromReply(admitted.settledReply);
+          }
+          if (admitted.execution === undefined) {
+            return finish(
+              transientHostedError(
+                409,
+                "hosted_admission_unavailable",
+                "The hosted admission token has no owner turn in flight.",
+              ),
+            );
+          }
+          if (execution.mode === "start") {
+            return finish(
+              Response.json({
+                ok: true,
+                v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+                outcome: "started",
+              }),
+            );
+          }
+          return finish(
+            Response.json({
+              ok: true,
+              v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+              outcome: "running",
+            }),
+          );
+        }
+
         admitted.sessionPublicId = execution.sessionPublicId;
 
         if (execution.mode === "enqueue") {
+          const network = await finishNetworkWait("execution");
+          guestNetwork = network.timing;
+          if (network.response !== undefined) {
+            return finish(network.response);
+          }
           const enqueueOutcome = await enqueueIntoActiveOwner({
             activeOwners,
             sessionPublicId: execution.sessionPublicId,
@@ -786,198 +983,259 @@ export function registerHostedDeliveryRoute(input: {
           );
         }
 
-        admitted.execution ??= (async (): Promise<ExecutionReply> => {
-          const startedAt = performance.now();
-          const executionId = hostedExecutionDiagId(execution.admissionToken);
-          const sinks: HostedExecutionFlushSinks = {
-            ...(input.stateRoot === undefined ? {} : { stateRoot: input.stateRoot }),
-            ...(input.persistSessionRun === undefined
-              ? {}
-              : { persistSessionRun: input.persistSessionRun }),
-            ...(input.flushStartLog === undefined ? {} : { flushStartLog: input.flushStartLog }),
-            ...(input.snapshotLogs === undefined ? {} : { snapshotLogs: input.snapshotLogs }),
-          };
-          const writeDiag = async (fields: {
-            sessionId: string;
-            turnStatus: string;
-            message?: string;
-            abortReason?: ReturnType<typeof abortReasonFromTurnStatus> | "execute_throw";
-            failureCode?: string;
-            errorCode?: string;
-            error?: unknown;
-          }): Promise<void> => {
-            const classification =
-              fields.failureCode === undefined
-                ? undefined
-                : hostedFailureClassification(fields.failureCode);
-            await flushHostedExecutionRecord(sinks, {
-              executionId,
-              sessionPublicId: execution.sessionPublicId,
-              sessionId: fields.sessionId,
-              turnStatus: fields.turnStatus,
-              durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
-              ...(fields.message === undefined ? {} : { message: fields.message }),
-              ...(fields.abortReason === undefined ? {} : { abortReason: fields.abortReason }),
-              failureCode: fields.failureCode,
-              ...(fields.errorCode === undefined ? {} : { errorCode: fields.errorCode }),
-              classification,
-              ...(fields.error === undefined ? {} : { error: fields.error }),
+        if (admitted.execution === undefined) {
+          admitted.expiresAt = Date.now() + ownerTurnPendingTtlMs;
+        }
+        admitted.execution ??= afterHostedWork(
+          input.flushOtel,
+          async (): Promise<ExecutionReply> => {
+            const network = await finishNetworkWait("execution");
+            guestNetwork = network.timing;
+            if (network.response !== undefined) {
+              return await responseToReply(finish(network.response));
+            }
+            const startedAt = performance.now();
+            const executionId = hostedExecutionDiagId(execution.admissionToken);
+            const sinks: HostedExecutionFlushSinks = {
+              ...(input.stateRoot === undefined ? {} : { stateRoot: input.stateRoot }),
+              ...(input.persistSessionRun === undefined
+                ? {}
+                : { persistSessionRun: input.persistSessionRun }),
+              ...(input.flushStartLog === undefined ? {} : { flushStartLog: input.flushStartLog }),
+              ...(input.snapshotLogs === undefined ? {} : { snapshotLogs: input.snapshotLogs }),
+            };
+            const writeDiag = async (fields: {
+              sessionId: string;
+              turnStatus: string;
+              message?: string;
+              abortReason?: ReturnType<typeof abortReasonFromTurnStatus> | "execute_throw";
+              failureCode?: string;
+              errorCode?: string;
+              error?: unknown;
+            }): Promise<void> => {
+              const classification =
+                fields.failureCode === undefined
+                  ? undefined
+                  : hostedFailureClassification(fields.failureCode);
+              await flushHostedExecutionRecord(sinks, {
+                executionId,
+                sessionPublicId: execution.sessionPublicId,
+                sessionId: fields.sessionId,
+                turnStatus: fields.turnStatus,
+                durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
+                ...(fields.message === undefined ? {} : { message: fields.message }),
+                ...(fields.abortReason === undefined ? {} : { abortReason: fields.abortReason }),
+                failureCode: fields.failureCode,
+                ...(fields.errorCode === undefined ? {} : { errorCode: fields.errorCode }),
+                classification,
+                ...(fields.error === undefined ? {} : { error: fields.error }),
+              });
+            };
+            // Claim the file before the turn runs. If a later status request
+            // fails, the host reads this record while the turn may still be
+            // running; the marker prevents it from surfacing the previous
+            // delivery's terminal record.
+            await writeDiag({
+              sessionId: "",
+              turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
             });
-          };
-          // Claim the file before the turn runs. The host reads it after its
-          // own POST returns, which for a 9-minute timeout is while this turn
-          // is still going; without this marker that read would surface the
-          // PREVIOUS delivery's terminal record as if it were this one's.
-          await writeDiag({
-            sessionId: "",
-            turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
-          });
-          let sessionId = "";
-          const owner: ActiveOwnerContext = {
-            primaryDeliveryId: admitted.deliveryId,
-            acceptedDeliveryIds: [],
-            accepting: true,
-            inflightInjects: new Set(),
-            enqueueResults: new Map(),
-          };
-          activeOwners.set(execution.sessionPublicId, owner);
-          return await runWithHostedExecutionLatency(
-            { channelKind: admitted.channelKind },
-            async () => {
-              let completionAt: number | undefined;
-              let drainAt: number | undefined;
-              try {
-                const args = input.buildHandlerArgs(
-                  admitted.send.channelId,
-                  execution.sessionPublicId,
-                );
-                const session = await args.send(admitted.send.message, {
-                  ...admitted.send.options,
-                  mailboxContinuation: {
-                    key: admitted.send.mailboxContinuationKey,
-                  },
-                });
-                sessionId = session.id;
-                // The pre-turn claim used an empty sessionId. Stamp the
-                // engine id now so a dashboard / session-view poll that
-                // only has the factory `ses_…` can follow `session-events/`.
-                await writeDiag({
-                  sessionId,
-                  turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
-                });
-                const outcome = await session.waitForCompletion();
-                completionAt = hostedExecutionNow();
-                // Status is the owner turn. waitForCompletion still waited
-                // for any drained successor so this process is not parked
-                // mid-follow-up; a successor failure must not 503-retry the
-                // owner after satellites already ran.
-                // Close acceptance at the turn boundary, before durability
-                // work creates an idle-but-still-addressable window.
-                owner.accepting = false;
-                if (owner.inflightInjects.size > 0) {
-                  await Promise.allSettled([...owner.inflightInjects]);
-                }
-                // Failed turns drain too: their record/continuation updates must
-                // survive the park just like a finished turn's.
-                await input.drainSessionDurability?.(session.id);
-                drainAt = hostedExecutionNow();
-                const consumedDeliveryIds = [owner.primaryDeliveryId, ...owner.acceptedDeliveryIds];
-                if (consumedDeliveryIds.length > HOSTED_MAX_CONSUMED_DELIVERY_IDS) {
-                  throw new Error(
-                    `hosted execute consumedDeliveryIds length ${String(consumedDeliveryIds.length)} exceeds cap ${String(HOSTED_MAX_CONSUMED_DELIVERY_IDS)}`,
+            let sessionId = "";
+            const owner: ActiveOwnerContext = {
+              primaryDeliveryId: admitted.deliveryId,
+              acceptedDeliveryIds: [],
+              accepting: true,
+              inflightInjects: new Set(),
+              enqueueResults: new Map(),
+            };
+            activeOwners.set(execution.sessionPublicId, owner);
+            return await runWithHostedExecutionLatency(
+              { channelKind: admitted.channelKind },
+              async () => {
+                let completionAt: number | undefined;
+                let drainAt: number | undefined;
+                try {
+                  const args = input.buildHandlerArgs(
+                    admitted.send.channelId,
+                    execution.sessionPublicId,
                   );
+                  const session = await args.send(admitted.send.message, {
+                    ...admitted.send.options,
+                    mailboxContinuation: {
+                      key: admitted.send.mailboxContinuationKey,
+                    },
+                  });
+                  sessionId = session.id;
+                  // The pre-turn claim used an empty sessionId. Stamp the
+                  // engine id now so a dashboard / session-view poll that
+                  // only has the factory `ses_…` can follow `session-events/`.
+                  await writeDiag({
+                    sessionId,
+                    turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
+                  });
+                  const outcome = await session.waitForCompletion();
+                  completionAt = hostedExecutionNow();
+                  // Status is the owner turn. waitForCompletion still waited
+                  // for any drained successor so this process is not parked
+                  // mid-follow-up; a successor failure must not 503-retry the
+                  // owner after satellites already ran.
+                  // Close acceptance at the turn boundary, before durability
+                  // work creates an idle-but-still-addressable window.
+                  owner.accepting = false;
+                  if (owner.inflightInjects.size > 0) {
+                    await Promise.allSettled([...owner.inflightInjects]);
+                  }
+                  // Failed turns drain too: their record/continuation updates must
+                  // survive the park just like a finished turn's.
+                  await input.drainSessionDurability?.(session.id);
+                  drainAt = hostedExecutionNow();
+                  const consumedDeliveryIds = [
+                    owner.primaryDeliveryId,
+                    ...owner.acceptedDeliveryIds,
+                  ];
+                  if (consumedDeliveryIds.length > HOSTED_MAX_CONSUMED_DELIVERY_IDS) {
+                    throw new Error(
+                      `hosted execute consumedDeliveryIds length ${String(consumedDeliveryIds.length)} exceeds cap ${String(HOSTED_MAX_CONSUMED_DELIVERY_IDS)}`,
+                    );
+                  }
+                  // Evict before the reply: TAS parks and hibernates this process
+                  // as soon as the POST returns. A leftover SDK handle freezes a
+                  // dead Connect/HTTP2 session that the next wake then reuses.
+                  evictHostedSdkSessions(
+                    input.evictSdkSession,
+                    session.id,
+                    execution.sessionPublicId,
+                  );
+                  const hostedFailure =
+                    outcome.status === "finished"
+                      ? undefined
+                      : hostedFailureForUnfinishedTurn(outcome);
+                  await writeDiag({
+                    sessionId: session.id,
+                    turnStatus: outcome.status,
+                    message: outcome.errorMessage,
+                    abortReason: abortReasonFromTurnStatus(
+                      outcome.status,
+                      outcome.cancellationReason,
+                    ),
+                    failureCode: hostedFailure?.error,
+                    ...(outcome.errorCode === undefined ? {} : { errorCode: outcome.errorCode }),
+                  });
+                  const reply =
+                    hostedFailure !== undefined
+                      ? {
+                          status: 503,
+                          body: {
+                            ok: false,
+                            error: hostedFailure.error,
+                            retry: hostedFailure.retry,
+                            classification: hostedFailureClassification(hostedFailure.error),
+                            turnStatus: outcome.status,
+                            message: outcome.errorMessage,
+                            ...(outcome.errorCode === undefined
+                              ? {}
+                              : { errorCode: outcome.errorCode }),
+                          },
+                        }
+                      : {
+                          status: 200,
+                          body: {
+                            ok: true,
+                            v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+                            outcome: "send",
+                            consumedDeliveryIds,
+                          },
+                        };
+                  // Finalize as late as possible so `post_drain` and `total`
+                  // include eviction + diag write after durability drain.
+                  latencySnapshot = finalizeHostedExecutionLatency({
+                    completionAt,
+                    drainAt,
+                    endedAt: hostedExecutionNow(),
+                  });
+                  return await responseToReply(
+                    finish(Response.json(reply.body, { status: reply.status })),
+                  );
+                } catch (error) {
+                  owner.accepting = false;
+                  if (owner.inflightInjects.size > 0) {
+                    await Promise.allSettled([...owner.inflightInjects]);
+                  }
+                  evictHostedSdkSessions(
+                    input.evictSdkSession,
+                    sessionId,
+                    execution.sessionPublicId,
+                  );
+                  const thrownErrorCode = describeErrorCode(error);
+                  await writeDiag({
+                    sessionId: "",
+                    turnStatus: "error",
+                    message: error instanceof Error ? error.message : String(error),
+                    abortReason: "execute_throw",
+                    failureCode: "internal_error",
+                    error,
+                    ...(thrownErrorCode === undefined ? {} : { errorCode: thrownErrorCode }),
+                  });
+                  const endedAt = hostedExecutionNow();
+                  // Preserve completion/drain marks when the failure happened
+                  // during post-drain work; otherwise collapse to endedAt.
+                  latencySnapshot = finalizeHostedExecutionLatency({
+                    completionAt: completionAt ?? endedAt,
+                    drainAt: drainAt ?? endedAt,
+                    endedAt,
+                  });
+                  throw error;
+                } finally {
+                  if (activeOwners.get(execution.sessionPublicId) === owner) {
+                    activeOwners.delete(execution.sessionPublicId);
+                  }
                 }
-                // Evict before the reply: TAS parks and hibernates this process
-                // as soon as the POST returns. A leftover SDK handle freezes a
-                // dead Connect/HTTP2 session that the next wake then reuses.
-                evictHostedSdkSessions(
-                  input.evictSdkSession,
-                  session.id,
-                  execution.sessionPublicId,
-                );
-                const hostedFailure =
-                  outcome.status === "finished"
-                    ? undefined
-                    : hostedFailureForUnfinishedTurn(outcome);
-                await writeDiag({
-                  sessionId: session.id,
-                  turnStatus: outcome.status,
-                  message: outcome.errorMessage,
-                  abortReason: abortReasonFromTurnStatus(
-                    outcome.status,
-                    outcome.cancellationReason,
-                  ),
-                  failureCode: hostedFailure?.error,
-                  ...(outcome.errorCode === undefined ? {} : { errorCode: outcome.errorCode }),
-                });
-                const reply =
-                  hostedFailure !== undefined
-                    ? {
-                        status: 503,
-                        body: {
-                          ok: false,
-                          error: hostedFailure.error,
-                          retry: hostedFailure.retry,
-                          classification: hostedFailureClassification(hostedFailure.error),
-                          turnStatus: outcome.status,
-                          message: outcome.errorMessage,
-                          ...(outcome.errorCode === undefined
-                            ? {}
-                            : { errorCode: outcome.errorCode }),
-                        },
-                      }
-                    : {
-                        status: 200,
-                        body: {
-                          ok: true,
-                          v: HOSTED_DELIVERY_PROTOCOL_VERSION,
-                          outcome: "send",
-                          consumedDeliveryIds,
-                        },
-                      };
-                // Finalize as late as possible so `post_drain` and `total`
-                // include eviction + diag write after durability drain.
-                latencySnapshot = finalizeHostedExecutionLatency({
-                  completionAt,
-                  drainAt,
-                  endedAt: hostedExecutionNow(),
-                });
-                return reply;
-              } catch (error) {
-                owner.accepting = false;
-                if (owner.inflightInjects.size > 0) {
-                  await Promise.allSettled([...owner.inflightInjects]);
-                }
-                evictHostedSdkSessions(input.evictSdkSession, sessionId, execution.sessionPublicId);
-                const thrownErrorCode = describeErrorCode(error);
-                await writeDiag({
-                  sessionId: "",
-                  turnStatus: "error",
-                  message: error instanceof Error ? error.message : String(error),
-                  abortReason: "execute_throw",
-                  failureCode: "internal_error",
-                  error,
-                  ...(thrownErrorCode === undefined ? {} : { errorCode: thrownErrorCode }),
-                });
-                const endedAt = hostedExecutionNow();
-                // Preserve completion/drain marks when the failure happened
-                // during post-drain work; otherwise collapse to endedAt.
-                latencySnapshot = finalizeHostedExecutionLatency({
-                  completionAt: completionAt ?? endedAt,
-                  drainAt: drainAt ?? endedAt,
-                  endedAt,
-                });
-                throw error;
-              } finally {
-                if (activeOwners.get(execution.sessionPublicId) === owner) {
-                  activeOwners.delete(execution.sessionPublicId);
-                }
-              }
-            },
+              },
+            );
+          },
+        ).then(
+          reply => {
+            admitted.settledReply = reply;
+            admitted.expiresAt = Date.now() + pendingTtlMs;
+            return reply;
+          },
+          error => {
+            admitted.settledReply = {
+              status: 503,
+              body: {
+                ok: false,
+                error: "internal_error",
+                retry: HOSTED_GUEST_RETRY_TERMINAL,
+                classification: hostedFailureClassification("internal_error"),
+                message: error instanceof Error ? error.message : String(error),
+              },
+            };
+            admitted.expiresAt = Date.now() + pendingTtlMs;
+            return admitted.settledReply;
+          },
+        );
+        if (execution.mode === "start") {
+          const quickReply = await Promise.race([
+            admitted.execution,
+            new Promise<undefined>(resolve => setImmediate(() => resolve(undefined))),
+          ]);
+          if (quickReply !== undefined) {
+            return responseFromReply(quickReply);
+          }
+          return finish(
+            Response.json({
+              ok: true,
+              v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+              outcome: "started",
+            }),
           );
-        })();
-        const reply = await admitted.execution;
-        return finish(Response.json(reply.body, { status: reply.status }));
+        }
+        return finish(
+          terminalHostedError(
+            400,
+            "invalid_hosted_execution",
+            "Owner execution requires start or status mode.",
+          ),
+        );
       }),
   });
 }