deepline 0.1.20 → 0.1.21

package/dist/repo/apps/play-runner-workers/src/coordinator-entry.ts

@@ -23,6 +23,7 @@ import {
 } from '@cloudflare/dynamic-workflows';
 import type { ExecutionPlan } from '../../../shared_libs/play-runtime/execution-plan';
 import type { PlayCallGovernanceSnapshot } from '../../../shared_libs/play-runtime/scheduler-backend';
+import type { PreloadedRuntimeDbSession } from '../../../shared_libs/play-runtime/db-session';
 import type {
   PlayRuntimeManifest,
   PlayRuntimeManifestMap,
@@ -54,6 +55,7 @@ export type PlayWorkflowParams = {
   executionPlan?: ExecutionPlan | null;
   childPlayManifests?: PlayRuntimeManifestMap | null;
   playCallGovernance?: PlayCallGovernanceSnapshot | null;
+  preloadedDbSessions?: PreloadedRuntimeDbSession[] | null;
   dynamicWorkerCode?: string | null;
   executorToken: string;
   baseUrl: string;
@@ -115,6 +117,57 @@ type CoordinatorPerfTraceInput = {
 
 type CoordinatorPerfTraceSink = (event: CoordinatorPerfTraceInput) => void;
 
+type CoordinatorTerminalState = {
+  runId: string;
+  status: 'completed' | 'failed' | 'cancelled';
+  result?: unknown;
+  error?: string | null;
+  totalRows?: unknown;
+  durationMs?: unknown;
+  playName?: string | null;
+  completedAt?: number;
+};
+
+type CoordinatorRunEvent =
+  | {
+      seq?: number;
+      runId: string;
+      type: 'status';
+      status: string;
+      ts: number;
+      logs?: string[];
+    }
+  | {
+      seq?: number;
+      runId: string;
+      type: 'log';
+      line: string;
+      ts: number;
+    }
+  | {
+      seq?: number;
+      runId: string;
+      type: 'progress';
+      status: string;
+      ts: number;
+      logs?: string[];
+      activeNodeId?: string | null;
+      activeArtifactTableNamespace?: string | null;
+      updatedAt?: number | null;
+    }
+  | {
+      seq?: number;
+      runId: string;
+      type: 'terminal';
+      status: 'completed' | 'failed' | 'cancelled';
+      ts: number;
+      result?: unknown;
+      error?: string | null;
+      totalRows?: unknown;
+      durationMs?: unknown;
+      playName?: string | null;
+    };
+
 type InlineWorkerRunResponse = {
   status?: 'completed' | 'failed';
   result?: unknown;
@@ -176,7 +229,12 @@ interface CoordinatorEnv {
   HARNESS?: import('../../play-harness-worker/src/rpc-types').PlayHarnessRpc;
 }
 
-const WORKFLOW_READ_ONLY_ACTIONS = new Set(['', 'observe', 'result', 'status']);
+const WORKFLOW_READ_ONLY_ACTIONS = new Set([
+  '',
+  'result',
+  'status',
+  'tail',
+]);
 
 function authorizeCoordinatorControlRequest(input: {
   request: Request;
@@ -327,6 +385,106 @@ async function listCoordinatorPerfTrace(
   );
 }
 
+async function writeCoordinatorTerminalState(
+  env: CoordinatorEnv,
+  state: CoordinatorTerminalState,
+): Promise<void> {
+  const stub = env.PLAY_DEDUP.get(env.PLAY_DEDUP.idFromName(state.runId));
+  const response = await stub.fetch(
+    'https://deepline.dedup.internal/terminal-set',
+    {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        ...state,
+        completedAt: state.completedAt ?? Date.now(),
+      }),
+    },
+  );
+  if (!response.ok) {
+    throw new Error(`coordinator terminal set failed ${response.status}`);
+  }
+}
+
+async function appendCoordinatorRunEvent(
+  env: CoordinatorEnv,
+  event: CoordinatorRunEvent,
+): Promise<void> {
+  const stub = env.PLAY_DEDUP.get(env.PLAY_DEDUP.idFromName(event.runId));
+  const response = await stub.fetch('https://deepline.dedup.internal/event-add', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(event),
+  });
+  if (!response.ok) {
+    throw new Error(`coordinator event append failed ${response.status}`);
+  }
+}
+
+async function listCoordinatorRunEvents(input: {
+  env: CoordinatorEnv;
+  runId: string;
+  afterSeq: number;
+  timeoutMs: number;
+}): Promise<{ events: CoordinatorRunEvent[]; latestSeq: number }> {
+  const stub = input.env.PLAY_DEDUP.get(
+    input.env.PLAY_DEDUP.idFromName(input.runId),
+  );
+  const response = await stub.fetch(
+    `https://deepline.dedup.internal/event-list?afterSeq=${encodeURIComponent(
+      String(Math.max(0, Math.floor(input.afterSeq))),
+    )}&timeoutMs=${encodeURIComponent(
+      String(Math.max(0, Math.floor(input.timeoutMs))),
+    )}`,
+  );
+  if (!response.ok) {
+    throw new Error(`coordinator event list failed ${response.status}`);
+  }
+  const body = (await response.json().catch(() => ({}))) as {
+    events?: unknown;
+    latestSeq?: unknown;
+  };
+  return {
+    events: Array.isArray(body.events)
+      ? body.events.filter(
+          (event): event is CoordinatorRunEvent =>
+            isRecord(event) &&
+            typeof event.runId === 'string' &&
+            event.runId === input.runId &&
+            typeof event.type === 'string' &&
+            typeof event.ts === 'number',
+        )
+      : [],
+    latestSeq: typeof body.latestSeq === 'number' ? body.latestSeq : input.afterSeq,
+  };
+}
+
+async function readCoordinatorTerminalState(
+  env: CoordinatorEnv,
+  runId: string,
+): Promise<CoordinatorTerminalState | null> {
+  const stub = env.PLAY_DEDUP.get(env.PLAY_DEDUP.idFromName(runId));
+  const response = await stub.fetch(
+    'https://deepline.dedup.internal/terminal-get',
+  );
+  if (!response.ok) {
+    throw new Error(`coordinator terminal get failed ${response.status}`);
+  }
+  const body = (await response.json().catch(() => ({}))) as {
+    state?: unknown;
+  };
+  const state = body.state;
+  if (!isRecord(state) || state.runId !== runId) return null;
+  if (
+    state.status !== 'completed' &&
+    state.status !== 'failed' &&
+    state.status !== 'cancelled'
+  ) {
+    return null;
+  }
+  return state as CoordinatorTerminalState;
+}
+
 function workflowEventType(name: string): string {
   const normalized = name
     .trim()
@@ -361,17 +519,20 @@ type PooledWorkflowBootstrapPayload = {
 };
 
 const WORKFLOW_POOL_PROTOCOL_VERSION =
-  'pooled-workflow-wait-v4-waiting-only';
+  'pooled-workflow-wait-v14-ready-signal-http-storage';
 const WORKFLOW_POOL_DO_NAME = 'workflow-pool:v2';
 const WORKFLOW_POOL_START_EVENT_TYPE = 'play_start';
 const WORKFLOW_POOL_TTL_MS = 8 * 60 * 1000;
-const WORKFLOW_POOL_TARGET_SIZE = 2;
+const WORKFLOW_POOL_TARGET_SIZE = 16;
 const WORKFLOW_POOL_READY_TIMEOUT_MS = 1_500;
 const WORKFLOW_POOL_READY_POLL_MS = 250;
 const WORKFLOW_POOL_REFILL_ON_MISS_TIMEOUT_MS = 2_500;
-const WORKFLOW_POOL_REFILL_ON_MISS_MIN_AVAILABLE = 1;
+const WORKFLOW_POOL_REFILL_ON_MISS_MIN_AVAILABLE = 4;
 const WORKFLOW_POOL_CONTROL_TIMEOUT_MS = 750;
-
+const SUBMIT_INITIAL_STATE_MAX_WAIT_MS = 0;
+const SUBMIT_INITIAL_STATE_POLL_MS = 50;
+const WORKFLOW_POOL_DISABLED_REASON =
+  'Cloudflare Workflows start runs directly; waitForEvent is reserved for real durable external waits.';
 function buildDynamicWorkflowMetadata(
   params: PlayWorkflowParams,
 ): DynamicWorkflowMetadata {
@@ -442,13 +603,45 @@ function readWorkflowTraceContext(event: unknown): {
 }
 
 function workflowPoolEnabled(): boolean {
-  return true;
+  return false;
 }
 
 function workflowPoolTargetSize(): number {
   return WORKFLOW_POOL_TARGET_SIZE;
 }
 
+async function waitForSubmitInitialState(input: {
+  instance: WorkflowInstance;
+  runId: string;
+  waitMs: number;
+}): Promise<Record<string, unknown> | null> {
+  const waitMs = Math.max(
+    0,
+    Math.min(Math.floor(input.waitMs), SUBMIT_INITIAL_STATE_MAX_WAIT_MS),
+  );
+  if (waitMs <= 0) return null;
+  const startedAt = Date.now();
+  let status = await input.instance.status();
+  while (Date.now() - startedAt < waitMs) {
+    const result = mapWorkflowResult(input.runId, status);
+    if (
+      result.status === 'completed' ||
+      result.status === 'failed' ||
+      result.status === 'cancelled'
+    ) {
+      return result as unknown as Record<string, unknown>;
+    }
+    await sleep(SUBMIT_INITIAL_STATE_POLL_MS);
+    status = await input.instance.status();
+  }
+  const result = mapWorkflowResult(input.runId, status);
+  return result.status === 'completed' ||
+    result.status === 'failed' ||
+    result.status === 'cancelled'
+    ? (result as unknown as Record<string, unknown>)
+    : null;
+}
+
 async function createDynamicWorkflowInstance(input: {
   env: CoordinatorEnv;
   id: string;
@@ -477,23 +670,32 @@ async function callWorkflowPool<T>(
     1,
     Math.floor(init?.timeoutMs ?? WORKFLOW_POOL_CONTROL_TIMEOUT_MS),
   );
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
   try {
     const fetchInit: RequestInit = { ...(init ?? {}) };
     delete (fetchInit as { timeoutMs?: number }).timeoutMs;
     delete fetchInit.signal;
-    const response = await workflowPoolDurableObject(env).fetch(
-      `https://deepline.workflow-pool.internal${path}`,
-      {
-        ...fetchInit,
-        signal: controller.signal,
-        headers: {
-          'content-type': 'application/json',
-          ...(init?.headers ?? {}),
+    const response = await Promise.race([
+      workflowPoolDurableObject(env).fetch(
+        `https://deepline.workflow-pool.internal${path}`,
+        {
+          ...fetchInit,
+          headers: {
+            'content-type': 'application/json',
+            ...(init?.headers ?? {}),
+          },
         },
-      },
-    );
+      ),
+      new Promise<Response>((_, reject) => {
+        timeoutId = setTimeout(
+          () =>
+            reject(
+              new Error(`workflow pool ${path} timed out after ${timeoutMs}ms`),
+            ),
+          timeoutMs,
+        );
+      }),
+    ]);
     if (!response.ok) {
       throw new Error(
         `workflow pool ${path} failed ${response.status}: ${(
@@ -511,7 +713,7 @@ async function callWorkflowPool<T>(
     }
     throw error;
   } finally {
-    clearTimeout(timer);
+    if (timeoutId) clearTimeout(timeoutId);
   }
 }
 
@@ -531,6 +733,7 @@ type WorkflowPoolRefillResult = WorkflowPoolCounts & {
 
 type WorkflowPoolListEntry = {
   id: string;
+  state: string;
   createdAt: number;
   readyAt: number | null;
   expiresAt: number;
@@ -568,6 +771,7 @@ async function listWorkflowPoolEntries(
     )
     .map((entry) => ({
       id: typeof entry.id === 'string' ? entry.id : '',
+      state: typeof entry.state === 'string' ? entry.state : '',
       createdAt:
         typeof entry.createdAt === 'number' && Number.isFinite(entry.createdAt)
           ? entry.createdAt
@@ -602,6 +806,24 @@ async function addWorkflowPoolIds(
   });
 }
 
+async function markWorkflowPoolIdReady(
+  env: CoordinatorEnv,
+  poolId: string,
+): Promise<boolean> {
+  const body = await callWorkflowPool<{ ready?: unknown }>(
+    env,
+    '/pool-ready',
+    {
+      method: 'POST',
+      body: JSON.stringify({
+        poolId,
+        version: WORKFLOW_POOL_PROTOCOL_VERSION,
+      }),
+    },
+  );
+  return body.ready === true;
+}
+
 async function promoteWorkflowPoolIds(
   env: CoordinatorEnv,
   ids: string[],
@@ -632,13 +854,14 @@ async function deleteWorkflowPoolIds(
 
 async function leaseWorkflowPoolId(
   env: CoordinatorEnv,
+  runId: string,
 ): Promise<string | null> {
   const body = await callWorkflowPool<{ id?: unknown }>(
     env,
-    `/pool-lease?version=${encodeURIComponent(WORKFLOW_POOL_PROTOCOL_VERSION)}`,
+    `/pool-claim?version=${encodeURIComponent(WORKFLOW_POOL_PROTOCOL_VERSION)}`,
     {
       method: 'POST',
-      body: '{}',
+      body: JSON.stringify({ runId }),
     },
   );
   return typeof body.id === 'string' && body.id ? body.id : null;
@@ -702,27 +925,36 @@ function workflowStatusName(status: InstanceStatus | null): string {
 }
 
 function workflowPoolStatusIsReady(statusName: string): boolean {
-  // Only a Workflow explicitly blocked on waitForEvent is safe to lease.
-  // A generic "running" instance may already be executing a previous play; if
-  // we send a new start event to it, the submitted run can stay running forever
-  // while callbacks continue updating the previous runId.
-  return statusName === 'waiting';
+  // This is only a liveness guard. Readiness itself comes from the pooled
+  // Workflow calling /pool-ready after waitForEvent("play_start") has been
+  // created, because Cloudflare may report an armed wait as "running".
+  return statusName === 'running' || statusName === 'waiting';
 }
 
-async function waitForWorkflowPoolReady(instance: WorkflowInstance): Promise<{
+async function waitForWorkflowPoolReadySignal(input: {
+  env: CoordinatorEnv;
+  instance: WorkflowInstance;
+  poolId: string;
+}): Promise<{
   ready: boolean;
   status: string;
   ms: number;
   polls: number;
 }> {
   const startedAt = Date.now();
-  let lastStatus: InstanceStatus | null = null;
+  let lastStatusName = 'unknown';
   let polls = 0;
   while (Date.now() - startedAt < WORKFLOW_POOL_READY_TIMEOUT_MS) {
-    lastStatus = await instance.status();
     polls += 1;
-    const statusName = workflowStatusName(lastStatus);
-    if (workflowPoolStatusIsReady(statusName)) {
+    const [entry, status] = await Promise.all([
+      listWorkflowPoolEntries(input.env)
+        .then((entries) => entries.find((candidate) => candidate.id === input.poolId))
+        .catch(() => undefined),
+      input.instance.status().catch(() => null),
+    ]);
+    const statusName = workflowStatusName(status);
+    lastStatusName = statusName;
+    if (entry?.state === 'ready' && entry.readyAt !== null) {
       return {
         ready: true,
         status: statusName,
@@ -733,7 +965,8 @@ async function waitForWorkflowPoolReady(instance: WorkflowInstance): Promise<{
     if (
       statusName === 'complete' ||
       statusName === 'errored' ||
-      statusName === 'terminated'
+      statusName === 'terminated' ||
+      statusName === 'unknown'
     ) {
       return {
         ready: false,
@@ -742,13 +975,11 @@ async function waitForWorkflowPoolReady(instance: WorkflowInstance): Promise<{
         polls,
       };
     }
-    await new Promise((resolve) =>
-      setTimeout(resolve, WORKFLOW_POOL_READY_POLL_MS),
-    );
+    await sleep(WORKFLOW_POOL_READY_POLL_MS);
   }
   return {
     ready: false,
-    status: workflowStatusName(lastStatus),
+    status: lastStatusName,
     ms: Date.now() - startedAt,
     polls,
   };
@@ -775,11 +1006,13 @@ async function refillWorkflowPoolOnce(
   for (const entry of warmingEntries) {
     const instance = await env.PLAY_WORKFLOW.get(entry.id);
     try {
+      if (entry.state === 'ready' && entry.readyAt !== null) {
+        promotedIds.push(entry.id);
+        continue;
+      }
       const status = await instance.status().catch(() => null);
       const statusName = workflowStatusName(status);
-      if (workflowPoolStatusIsReady(statusName)) {
-        promotedIds.push(entry.id);
-      } else if (
+      if (
         statusName === 'complete' ||
         statusName === 'errored' ||
         statusName === 'terminated' ||
@@ -808,48 +1041,64 @@ async function refillWorkflowPoolOnce(
       removed: removedIds.length,
     };
   }
-  const readyCreatedIds: string[] = [];
-  const warmingCreatedIds: string[] = [];
-  for (let i = 0; i < needed; i += 1) {
-    const poolId = `pool-v2-${Date.now().toString(36)}-${crypto.randomUUID().slice(0, 12)}`;
-    const instance = await env.PLAY_WORKFLOW.create({
-      id: poolId,
-      params: {
-        __deeplinePooledWorkflow: true,
-        poolId,
-        createdAt: Date.now(),
-      } satisfies PooledWorkflowBootstrapPayload,
-    });
-    try {
-      const readiness = await waitForWorkflowPoolReady(instance);
-      recordCoordinatorPerfTrace({
-        runId: poolId,
-        phase: 'coordinator.workflow_pool_ready',
-        ms: readiness.ms,
-        graphHash: 'workflow-pool',
-        extra: {
-          ready: readiness.ready,
-          status: readiness.status,
-          polls: readiness.polls,
-        },
+  const created = await Promise.all(
+    Array.from({ length: needed }, async () => {
+      const poolId = `pool-v2-${Date.now().toString(36)}-${crypto.randomUUID().slice(0, 12)}`;
+      await addWorkflowPoolIds(env, [poolId], { ready: false });
+      const instance = await env.PLAY_WORKFLOW.create({
+        id: poolId,
+        params: {
+          __deeplinePooledWorkflow: true,
+          poolId,
+          createdAt: Date.now(),
+        } satisfies PooledWorkflowBootstrapPayload,
       });
-      if (readiness.ready) {
-        readyCreatedIds.push(poolId);
-      } else if (
-        readiness.status === 'complete' ||
-        readiness.status === 'errored' ||
-        readiness.status === 'terminated' ||
-        readiness.status === 'unknown'
-      ) {
-        removedIds.push(poolId);
-        await instance.terminate().catch(() => undefined);
-      } else {
-        warmingCreatedIds.push(poolId);
+      try {
+        const readiness = await waitForWorkflowPoolReadySignal({
+          env,
+          instance,
+          poolId,
+        });
+        recordCoordinatorPerfTrace({
+          runId: poolId,
+          phase: 'coordinator.workflow_pool_ready',
+          ms: readiness.ms,
+          graphHash: 'workflow-pool',
+          extra: {
+            ready: readiness.ready,
+            status: readiness.status,
+            polls: readiness.polls,
+          },
+        });
+        if (readiness.ready) {
+          return { id: poolId, state: 'ready' as const };
+        }
+        if (
+          readiness.status === 'complete' ||
+          readiness.status === 'errored' ||
+          readiness.status === 'terminated' ||
+          readiness.status === 'unknown'
+        ) {
+          await instance.terminate().catch(() => undefined);
+          return { id: poolId, state: 'removed' as const };
+        }
+        return { id: poolId, state: 'warming' as const };
+      } finally {
+        disposeRpcStub(instance);
       }
-    } finally {
-      disposeRpcStub(instance);
-    }
-  }
+    }),
+  );
+  const readyCreatedIds = created
+    .filter((entry) => entry.state === 'ready')
+    .map((entry) => entry.id);
+  const warmingCreatedIds = created
+    .filter((entry) => entry.state === 'warming')
+    .map((entry) => entry.id);
+  removedIds.push(
+    ...created
+      .filter((entry) => entry.state === 'removed')
+      .map((entry) => entry.id),
+  );
   await Promise.all([
     addWorkflowPoolIds(env, readyCreatedIds, { ready: true }),
     addWorkflowPoolIds(env, warmingCreatedIds, { ready: false }),
@@ -928,7 +1177,10 @@ async function submitViaPooledWorkflow(input: {
   }
   const leaseStartedAt = Date.now();
   let leaseError: string | null = null;
-  let pooledInstanceId = await leaseWorkflowPoolId(input.env).catch((error) => {
+  const pooledInstanceId = await leaseWorkflowPoolId(
+    input.env,
+    input.params.runId,
+  ).catch((error) => {
     leaseError = error instanceof Error ? error.message : String(error);
     return null;
   });
@@ -952,50 +1204,26 @@ async function submitViaPooledWorkflow(input: {
   });
 
   if (!pooledInstanceId) {
-    // A pool miss is often a timing gap rather than a true lack of warm
-    // capacity. Wait briefly for refill/promotion, then retry lease once
-    // before falling back to a cold workflow create.
-    const refillStartedAt = Date.now();
-    const refillResult = await refillWorkflowPool(input.env, {
-      waitReady: true,
-      minAvailable: WORKFLOW_POOL_REFILL_ON_MISS_MIN_AVAILABLE,
-      waitTimeoutMs: WORKFLOW_POOL_REFILL_ON_MISS_TIMEOUT_MS,
-    }).catch(() => null);
+    // A pool miss must not block the user path. Refilling is handled by the
+    // caller's waitUntil after submit, so fall through to cold create now.
+    const counts = missCounts ?? (await workflowPoolCount(input.env).catch(() => null));
     input.recordSubmitTiming({
       phase: 'coordinator.workflow_pool_refill_on_miss',
-      ms: Date.now() - refillStartedAt,
+      ms: 0,
       graphHash: input.params.graphHash ?? null,
-      extra:
-        refillResult === null
-          ? { ok: false }
-          : {
-              ok: true,
-              available: refillResult.available,
-              warming: refillResult.warming,
-              created: refillResult.created,
-              promoted: refillResult.promoted,
-              removed: refillResult.removed,
-              waitedMs: refillResult.waitedMs,
-              waitIterations: refillResult.waitIterations,
-            },
+      extra: {
+        skipped: true,
+        reason: 'pool_miss_does_not_block_submit',
+        ...(counts
+          ? {
+              available: counts.available,
+              warming: counts.warming,
+              waitedMs: 0,
+              waitIterations: 0,
+            }
+          : {}),
+      },
     });
-    if (refillResult?.available) {
-      const retryStartedAt = Date.now();
-      let retryLeaseError: string | null = null;
-      pooledInstanceId = await leaseWorkflowPoolId(input.env).catch((error) => {
-        retryLeaseError = error instanceof Error ? error.message : String(error);
-        return null;
-      });
-      input.recordSubmitTiming({
-        phase: 'coordinator.workflow_pool_lease_retry',
-        ms: Date.now() - retryStartedAt,
-        graphHash: input.params.graphHash ?? null,
-        extra: {
-          pooled: Boolean(pooledInstanceId),
-          ...(retryLeaseError ? { error: retryLeaseError } : {}),
-        },
-      });
-    }
   }
 
   if (!pooledInstanceId) {
@@ -1032,20 +1260,6 @@ async function submitViaPooledWorkflow(input: {
     });
     return null;
   }
-  try {
-    await mapRunToWorkflowInstance({
-      env: input.env,
-      runId: input.params.runId,
-      instanceId: pooledInstanceId,
-    });
-  } catch (error) {
-    disposeRpcStub(instance);
-    throw new Error(
-      `workflow pool mapRunToWorkflowInstance failed after pooled workflow start for ${input.params.runId}: ${
-        error instanceof Error ? error.message : String(error)
-      }`,
-    );
-  }
   input.recordSubmitTiming({
     phase: 'coordinator.workflow_pool_send_event',
     ms: Date.now() - sendStartedAt,
@@ -1416,6 +1630,7 @@ function runRequestFromPlayWorkflowParams(params: PlayWorkflowParams): Record<st
     executionPlan: params.executionPlan ?? null,
     childPlayManifests: params.childPlayManifests ?? null,
     playCallGovernance: params.playCallGovernance ?? null,
+    preloadedDbSessions: params.preloadedDbSessions ?? null,
     coordinatorUrl: params.coordinatorUrl ?? null,
     totalRows: params.totalRows,
   };
@@ -1770,6 +1985,13 @@ export class RuntimeApi extends WorkerEntrypoint<CoordinatorEnv, undefined> {
         ? this.env.DEEPLINE_API_BASE_URL.trim()
         : 'https://code.deepline.com';
     const target = new URL(incoming.pathname + incoming.search, apiBaseUrl);
+    const runtimeStatusBody =
+      incoming.pathname === '/api/v2/plays/internal/runtime'
+        ? await request
+            .clone()
+            .json()
+            .catch(() => null)
+        : null;
     const forwarded = new Request(target.toString(), request);
     const bypassToken = this.env.VERCEL_PROTECTION_BYPASS_TOKEN;
     if (typeof bypassToken === 'string' && bypassToken) {
@@ -1785,9 +2007,41 @@ export class RuntimeApi extends WorkerEntrypoint<CoordinatorEnv, undefined> {
         `[RUNTIME_API] ${incoming.pathname} failed: status=${res.status} ` +
           `target=${target.toString()} body=${body.slice(0, 500)}`,
       );
+    } else {
+      await this.recordRuntimeStatusEvent(runtimeStatusBody).catch(() => null);
     }
     return res;
   }
+
+  private async recordRuntimeStatusEvent(body: unknown): Promise<void> {
+    if (!isRecord(body) || body.action !== 'update_run_status') {
+      return;
+    }
+    const runId = typeof body.playId === 'string' ? body.playId : '';
+    const status = typeof body.status === 'string' ? body.status : '';
+    if (!runId || !status) {
+      return;
+    }
+    await appendCoordinatorRunEvent(this.env, {
+      runId,
+      type: 'progress',
+      status,
+      ts: Date.now(),
+      logs: Array.isArray(body.liveLogs)
+        ? body.liveLogs.filter((line): line is string => typeof line === 'string')
+        : undefined,
+      activeNodeId:
+        typeof body.activeNodeId === 'string' ? body.activeNodeId : null,
+      activeArtifactTableNamespace:
+        typeof body.activeArtifactTableNamespace === 'string'
+          ? body.activeArtifactTableNamespace
+          : null,
+      updatedAt:
+        typeof body.lastCheckpointAt === 'number'
+          ? body.lastCheckpointAt
+          : null,
+    });
+  }
 }
 
 export class CoordinatorControl extends WorkerEntrypoint<
@@ -1855,6 +2109,13 @@ export class CoordinatorControl extends WorkerEntrypoint<
     }
     await appendCoordinatorPerfTrace(this.env, payload);
   }
+
+  async recordRunEvent(runId: string, event: CoordinatorRunEvent): Promise<void> {
+    if (!runId || event.runId !== runId) {
+      throw new Error('Run event runId mismatch.');
+    }
+    await appendCoordinatorRunEvent(this.env, event);
+  }
 }
 
 /**
@@ -1889,6 +2150,7 @@ export class DynamicWorkflow extends WorkflowEntrypoint<
     });
     let dispatchedEvent = event;
     if (isPooledWorkflowBootstrapPayload(workflowEvent.payload)) {
+      const pooledPayload = workflowEvent.payload;
       const waitingStep = step as {
         waitForEvent<T>(
           name: string,
@@ -1896,10 +2158,19 @@ export class DynamicWorkflow extends WorkflowEntrypoint<
         ): Promise<{ payload: Readonly<T>; timestamp: Date; type: string }>;
       };
       const waitStartedAt = Date.now();
-      const startEvent = await waitingStep.waitForEvent<DispatcherEnvelope>(
+      const startEventPromise = waitingStep.waitForEvent<DispatcherEnvelope>(
         'wait for pooled play start',
         { type: WORKFLOW_POOL_START_EVENT_TYPE, timeout: '10 minutes' },
       );
+      await markWorkflowPoolIdReady(this.env, pooledPayload.poolId).catch(
+        (error) => {
+          console.warn('[coordinator.workflow_pool] ready signal failed', {
+            poolId: pooledPayload.poolId,
+            message: error instanceof Error ? error.message : String(error),
+          });
+        },
+      );
+      const startEvent = await startEventPromise;
       dispatchedEvent = {
         payload: startEvent.payload,
         timestamp: startEvent.timestamp,
@@ -2001,6 +2272,18 @@ export class DynamicWorkflow extends WorkflowEntrypoint<
                   run(e: unknown, s: unknown): Promise<unknown>;
                 }
               ).run(innerEvent, innerStep);
+              const output = isRecord(result) ? result : null;
+              await writeCoordinatorTerminalState(env, {
+                runId: runIdForTrace,
+                status: 'completed',
+                result: output?.result ?? result,
+                totalRows: output?.totalRows ?? output?.outputRows ?? null,
+                durationMs: output?.durationMs ?? null,
+                playName:
+                  typeof output?.playName === 'string'
+                    ? output.playName
+                    : null,
+              });
               trace({
                 runId: runIdForTrace,
                 phase: 'coordinator.runner_run',
@@ -2038,6 +2321,14 @@ export class DynamicWorkflow extends WorkflowEntrypoint<
                   },
                 );
               });
+              await writeCoordinatorTerminalState(env, {
+                runId: runIdForTrace,
+                status: 'failed',
+                error:
+                  innerError instanceof Error
+                    ? innerError.message
+                    : String(innerError),
+              }).catch(() => undefined);
               throw innerError;
             }
           },
@@ -2051,7 +2342,7 @@ const coordinatorEntrypoint = {
   /**
    * HTTP entrypoint for the Vercel app to dispatch into. Routes:
    *   POST /workflow/{runId}/submit     → PLAY_WORKFLOW.create({ id, params })
-   *   GET  /workflow/{runId}/observe    → polling-compatible status snapshot
+   *   GET  /workflow/{runId}/tail       → ordered live run events after a cursor
    *   POST /workflow/{runId}/cancel     → Workflow instance terminate
    *   POST /workflow/{runId}/signal     → integration_event
    *   GET  /workflow/{runId}/result     → terminal envelope
@@ -2097,6 +2388,11 @@ const coordinatorEntrypoint = {
         deployMarker: env.DEEPLINE_COORDINATOR_DEPLOY_MARKER ?? null,
       });
     }
+    if (url.pathname === '/staged-files/put') {
+      const authError = authorizeCoordinatorControlRequest({ request, env });
+      if (authError) return authError;
+      return await handleStagedFilePut(request, env);
+    }
     if (url.pathname === '/workflow-pool/refill') {
       const internalAuthError = authorizeCoordinatorControlRequest({
         request,
@@ -2151,6 +2447,33 @@ const coordinatorEntrypoint = {
         ms: Date.now() - startedAt,
       });
     }
+    if (url.pathname === '/workflow-pool/debug') {
+      const internalAuthError = authorizeCoordinatorControlRequest({
+        request,
+        env,
+      });
+      if (internalAuthError) return internalAuthError;
+      const entries = await listWorkflowPoolEntries(env);
+      const detailed = [];
+      for (const entry of entries) {
+        const instance = await env.PLAY_WORKFLOW.get(entry.id);
+        try {
+          const status = await instance.status().catch(() => null);
+          detailed.push({
+            ...entry,
+            status: workflowStatusName(status),
+            mappedStatus: status ? mapWorkflowStatus(status) : 'running',
+          });
+        } finally {
+          disposeRpcStub(instance);
+        }
+      }
+      return Response.json({
+        ok: true,
+        enabled: workflowPoolEnabled(),
+        entries: detailed,
+      });
+    }
 
     // Workflow routes: /workflow/{runId}/{action}
     const wfMatch = url.pathname.match(/^\/workflow\/([^/]+)(?:\/(.+))?$/);
@@ -2362,45 +2685,54 @@ async function handleWorkflowRoute(input: {
     let instance: WorkflowInstance | null = null;
     try {
       const dispatchStartedAt = Date.now();
-      const poolStartedAt = Date.now();
-      instance = await submitViaPooledWorkflow({
+      recordSubmitTiming({
+        phase: 'coordinator.workflow_pool_attempt',
+        ms: 0,
+        graphHash: params.graphHash ?? null,
+        extra: {
+          usedPool: false,
+          disabled: true,
+          reason: WORKFLOW_POOL_DISABLED_REASON,
+        },
+      });
+      const createStartedAt = Date.now();
+      instance = await createDynamicWorkflowInstance({
         env,
+        id: defaultInstanceId,
         params,
-        recordSubmitTiming,
       });
-      const usedWorkflowPool = Boolean(instance);
       recordSubmitTiming({
-        phase: 'coordinator.workflow_pool_attempt',
-        ms: Date.now() - poolStartedAt,
+        phase: 'coordinator.workflow_create',
+        ms: Date.now() - createStartedAt,
         graphHash: params.graphHash ?? null,
-        extra: { usedPool: usedWorkflowPool },
+        extra: { instanceId: instance.id },
       });
-      if (!instance) {
-        const createStartedAt = Date.now();
-        instance = await createDynamicWorkflowInstance({
-          env,
-          id: defaultInstanceId,
-          params,
-        });
-        recordSubmitTiming({
-          phase: 'coordinator.workflow_create',
-          ms: Date.now() - createStartedAt,
-          graphHash: params.graphHash ?? null,
-          extra: { instanceId: instance.id, pooled: false },
-        });
-      } else {
-        recordSubmitTiming({
-          phase: 'coordinator.workflow_create',
-          ms: 0,
-          graphHash: params.graphHash ?? null,
-          extra: { instanceId: instance.id, pooled: true },
-        });
-      }
       recordSubmitTiming({
         phase: 'coordinator.dispatch_workflow',
         ms: Date.now() - dispatchStartedAt,
         graphHash: params.graphHash ?? null,
-        extra: { pooled: usedWorkflowPool },
+        extra: { startMode: 'direct_workflow_create' },
+      });
+      const initialWaitMsRaw = Number(
+        new URL(request.url).searchParams.get('initialWaitMs') ?? '0',
+      );
+      const initialStateStartedAt = Date.now();
+      const instanceState = await waitForSubmitInitialState({
+        instance,
+        runId: submittedRunId,
+        waitMs: Number.isFinite(initialWaitMsRaw) ? initialWaitMsRaw : 0,
+      });
+      recordSubmitTiming({
+        phase: 'coordinator.submit_initial_state',
+        ms: Date.now() - initialStateStartedAt,
+        graphHash: params.graphHash ?? null,
+        extra: {
+          waitMs: Number.isFinite(initialWaitMsRaw) ? initialWaitMsRaw : 0,
+          status:
+            typeof instanceState?.status === 'string'
+              ? instanceState.status
+              : null,
+        },
       });
       const totalMs = Date.now() - submitStartedAt;
       recordSubmitTiming({
@@ -2416,11 +2748,11 @@ async function handleWorkflowRoute(input: {
       return Response.json({
         runId,
         status: 'submitted',
-        instanceState: null,
+        workflowInstanceId: instance.id,
+        instanceState,
         coordinatorTimings,
       });
     } finally {
-      input.ctx?.waitUntil(refillWorkflowPool(env).catch(() => undefined));
       disposeRpcStub(instance);
     }
   }
@@ -2650,12 +2982,84 @@ async function handleWorkflowRoute(input: {
     }
   }
 
+  if (action === 'tail') {
+    const url = new URL(request.url);
+    const waitMs = Math.min(
+      Math.max(Number(url.searchParams.get('waitMs') ?? '0'), 0),
+      30_000,
+    );
+    const afterSeq = Math.max(
+      0,
+      Math.floor(Number(url.searchParams.get('afterSeq') ?? '0')),
+    );
+    const includeTrace = url.searchParams.get('trace') === '1';
+    const statusStartedAt = Date.now();
+    const eventResult = await listCoordinatorRunEvents({
+      env,
+      runId,
+      afterSeq,
+      timeoutMs: waitMs,
+    }).catch(() => null);
+    const coordinatorTrace =
+      includeTrace && eventResult?.events.length
+        ? await listCoordinatorPerfTrace(env, runId).catch(() => [])
+        : [];
+    const terminalEvent = eventResult?.events.find(
+      (event): event is Extract<CoordinatorRunEvent, { type: 'terminal' }> =>
+        event.type === 'terminal',
+    );
+    if (terminalEvent) {
+      return Response.json({
+        runId,
+        ...(terminalEvent.playName ? { playName: terminalEvent.playName } : {}),
+        status: terminalEvent.status,
+        result: terminalEvent.result ?? null,
+        error: terminalEvent.error ?? null,
+        totalRows: terminalEvent.totalRows ?? null,
+        durationMs: terminalEvent.durationMs ?? null,
+        events: eventResult?.events ?? [],
+        latestSeq: eventResult?.latestSeq ?? afterSeq,
+        wait: null,
+        coordinatorObserve: {
+          ms: Date.now() - statusStartedAt,
+          waitMs,
+          workflowStatus: 'terminal-event',
+          statusPolls: 0,
+          instanceId: null,
+        },
+        ...(includeTrace ? { coordinatorTrace } : {}),
+      });
+    }
+    return Response.json({
+      runId,
+      status: 'running',
+      events: eventResult?.events ?? [],
+      latestSeq: eventResult?.latestSeq ?? afterSeq,
+      wait: null,
+      coordinatorObserve: {
+        ms: Date.now() - statusStartedAt,
+        waitMs,
+        workflowStatus:
+          eventResult?.events.length ? 'event' : 'event-timeout',
+        statusPolls: 0,
+        instanceId: null,
+      },
+      ...(includeTrace ? { coordinatorTrace } : {}),
+    });
+  }
+
   // get() throws if the instance doesn't exist (Workflows local-mode wipes
   // state on wrangler dev reload, and superseded `--force` runs may target
   // an instance that was never created). Treat that as a no-op cancel.
   let instance: WorkflowInstance | null = null;
   try {
-    const instanceId = await resolveWorkflowInstanceIdForRun(env, runId);
+    const requestedInstanceId = new URL(request.url).searchParams
+      .get('instanceId')
+      ?.trim();
+    const instanceId =
+      requestedInstanceId && !isWorkflowMutatingAction(action)
+        ? requestedInstanceId
+        : await resolveWorkflowInstanceIdForRun(env, runId);
     instance = await env.PLAY_WORKFLOW.get(instanceId);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -2723,42 +3127,38 @@ async function handleWorkflowRoute(input: {
       });
     }
     if (
-      action === 'result' ||
-      action === 'status' ||
-      action === 'observe' ||
-      action === ''
+      action === 'result' || action === 'status' || action === ''
     ) {
-      const observeWaitMs =
-        action === 'observe'
-          ? Math.min(
-              Math.max(
-                Number(new URL(request.url).searchParams.get('waitMs') ?? '0'),
-                0,
-              ),
-              2_000,
-            )
-          : 0;
       const includeTrace =
         new URL(request.url).searchParams.get('trace') === '1';
       const statusStartedAt = Date.now();
-      let status = await instance.status();
-      let statusPolls = 1;
-      while (
-        observeWaitMs > 0 &&
-        Date.now() - statusStartedAt < observeWaitMs
-      ) {
-        const result = mapWorkflowResult(runId, status);
-        if (
-          result.status === 'completed' ||
-          result.status === 'failed' ||
-          result.status === 'cancelled'
-        ) {
-          break;
-        }
-        await new Promise((resolve) => setTimeout(resolve, 75));
-        status = await instance.status();
-        statusPolls += 1;
+      const terminalState = await readCoordinatorTerminalState(env, runId).catch(
+        () => null,
+      );
+      if (terminalState) {
+        const coordinatorTrace = includeTrace
+          ? await listCoordinatorPerfTrace(env, runId).catch(() => [])
+          : [];
+        return Response.json({
+          runId,
+          ...(terminalState.playName ? { playName: terminalState.playName } : {}),
+          status: terminalState.status,
+          result: terminalState.result ?? null,
+          error: terminalState.error ?? null,
+          totalRows: terminalState.totalRows ?? null,
+          durationMs: terminalState.durationMs ?? null,
+          wait: null,
+          coordinatorObserve: {
+            ms: Date.now() - statusStartedAt,
+            waitMs: 0,
+            workflowStatus: 'terminal-cache',
+            statusPolls: 0,
+            instanceId: instance.id,
+          },
+          ...(includeTrace ? { coordinatorTrace } : {}),
+        });
       }
+      const status = await instance.status();
       const result = mapWorkflowResult(runId, status);
       const observeMs = Date.now() - statusStartedAt;
       // If we forced a permanent-error fail-fast (status='failed' even
@@ -2797,9 +3197,9 @@ async function handleWorkflowRoute(input: {
         ...result,
         coordinatorObserve: {
           ms: observeMs,
-          waitMs: observeWaitMs,
+          waitMs: 0,
           workflowStatus: status.status,
-          statusPolls,
+          statusPolls: 1,
           instanceId: instance.id,
         },
         ...(includeTrace ? { coordinatorTrace } : {}),
@@ -2828,6 +3228,54 @@ function stableHash(value: string): string {
   return (hash >>> 0).toString(36);
 }
 
+const DYNAMIC_PLAY_WORKER_HARNESS_VERSION =
+  'h6-runtime-api-coordinator-deploy-scoped';
+const DYNAMIC_WORKER_BUNDLED_CODE_CACHE_MAX_ENTRIES = 64;
+const dynamicWorkerBundledCodeCache = new Map<string, string>();
+
+function dynamicPlayWorkerCacheKey(input: {
+  env: CoordinatorEnv;
+  graphHash: string;
+  artifactIdentity: string;
+}): string {
+  const deployMarker =
+    input.env.DEEPLINE_COORDINATOR_DEPLOY_MARKER?.trim() || 'local';
+  return [
+    'play',
+    input.graphHash,
+    input.artifactIdentity,
+    `harness=${DYNAMIC_PLAY_WORKER_HARNESS_VERSION}`,
+    `deploy=${deployMarker}`,
+  ].join(':');
+}
+
+function dynamicWorkerBundledCodeCacheKey(input: {
+  artifactStorageKey: string;
+  artifactHash?: string | null;
+}): string {
+  return `${input.artifactHash?.trim() || 'no-hash'}:${input.artifactStorageKey}`;
+}
+
+function readDynamicWorkerBundledCodeCache(key: string): string | null {
+  const cached = dynamicWorkerBundledCodeCache.get(key);
+  if (cached === undefined) return null;
+  dynamicWorkerBundledCodeCache.delete(key);
+  dynamicWorkerBundledCodeCache.set(key, cached);
+  return cached;
+}
+
+function writeDynamicWorkerBundledCodeCache(key: string, code: string): void {
+  dynamicWorkerBundledCodeCache.set(key, code);
+  while (
+    dynamicWorkerBundledCodeCache.size >
+    DYNAMIC_WORKER_BUNDLED_CODE_CACHE_MAX_ENTRIES
+  ) {
+    const oldestKey = dynamicWorkerBundledCodeCache.keys().next().value;
+    if (typeof oldestKey !== 'string') break;
+    dynamicWorkerBundledCodeCache.delete(oldestKey);
+  }
+}
+
 /**
  * Synchronous wrapper around env.LOADER.get for use inside the
  * createDynamicWorkflowEntrypoint loader callback. The framework's loader
@@ -2866,7 +3314,11 @@ function loadDynamicPlayWorkerSync(
   }
   const artifactIdentity =
     metadata.artifactHash?.trim() || stableHash(artifactStorageKey);
-  const workerCacheKey = `play:${graphHash}:${artifactIdentity}:harness=h5-runtime-api-coordinator`;
+  const workerCacheKey = dynamicPlayWorkerCacheKey({
+    env,
+    graphHash,
+    artifactIdentity,
+  });
   const runIdForTrace = metadata.runId ?? graphHash;
   const loaderGetStartedAt = Date.now();
   const stub = env.LOADER.get(workerCacheKey, async () => {
@@ -2952,7 +3404,11 @@ async function loadDynamicPlayWorker(
   }
   const artifactIdentity =
     metadata.artifactHash?.trim() || stableHash(artifactStorageKey);
-  const workerCacheKey = `play:${graphHash}:${artifactIdentity}:harness=h5-runtime-api-coordinator`;
+  const workerCacheKey = dynamicPlayWorkerCacheKey({
+    env,
+    graphHash,
+    artifactIdentity,
+  });
   const runIdForTrace = metadata.runId ?? graphHash;
   const loaderGetStartedAt = Date.now();
   const stub = env.LOADER.get(workerCacheKey, async () => {
@@ -3002,31 +3458,42 @@ async function loadDynamicWorkerBundledCode(input: {
   trace: CoordinatorPerfTraceSink;
 }): Promise<string> {
   const callbackStartedAt = Date.now();
-  let codeSource: 'inline' | 'r2' = 'inline';
+  let codeSource: 'inline' | 'r2' | 'memory' = 'inline';
   let r2Ms = 0;
-  const artifact = input.metadata.dynamicWorkerCode
-    ? null
-    : await (async () => {
-        codeSource = 'r2';
-        const r2StartedAt = Date.now();
-        try {
-          return await loadStoredPlayArtifactFromR2(
-            input.env,
-            input.artifactStorageKey,
-          );
-        } finally {
-          r2Ms = Date.now() - r2StartedAt;
-          input.trace({
-            runId: input.runIdForTrace,
-            phase: 'coordinator.loader_code_r2_get',
-            ms: r2Ms,
-            graphHash: input.graphHash,
-            extra: { artifactStorageKey: input.artifactStorageKey },
-          });
-        }
-      })();
-  const bundledCode =
-    input.metadata.dynamicWorkerCode ?? artifact?.artifact?.bundledCode;
+  const codeCacheKey = dynamicWorkerBundledCodeCacheKey({
+    artifactStorageKey: input.artifactStorageKey,
+    artifactHash: input.metadata.artifactHash,
+  });
+  let bundledCode = input.metadata.dynamicWorkerCode ?? null;
+  if (!bundledCode) {
+    bundledCode = readDynamicWorkerBundledCodeCache(codeCacheKey);
+    if (bundledCode) {
+      codeSource = 'memory';
+    }
+  }
+  if (!bundledCode) {
+    codeSource = 'r2';
+    const r2StartedAt = Date.now();
+    try {
+      const artifact = await loadStoredPlayArtifactFromR2(
+        input.env,
+        input.artifactStorageKey,
+      );
+      bundledCode = artifact?.artifact?.bundledCode ?? null;
+      if (typeof bundledCode === 'string' && bundledCode.length > 0) {
+        writeDynamicWorkerBundledCodeCache(codeCacheKey, bundledCode);
+      }
+    } finally {
+      r2Ms = Date.now() - r2StartedAt;
+      input.trace({
+        runId: input.runIdForTrace,
+        phase: 'coordinator.loader_code_r2_get',
+        ms: r2Ms,
+        graphHash: input.graphHash,
+        extra: { artifactStorageKey: input.artifactStorageKey },
+      });
+    }
+  }
   if (typeof bundledCode !== 'string' || bundledCode.length === 0) {
     throw new Error(
       `Stored play artifact ${input.artifactStorageKey} does not contain bundledCode.`,
@@ -3118,6 +3585,192 @@ export default {
 };
 `;
 
+function isAllowedStagedFileStorageKey(key: string): boolean {
+  if (!key || key.length > 2_048) return false;
+  if (key.startsWith('/') || key.includes('..') || key.includes('\\')) {
+    return false;
+  }
+  return key.startsWith('plays/v2/orgs/') || key.includes('/plays/v2/orgs/');
+}
+
+function decodeBase64ToUint8Array(value: string): Uint8Array {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+async function handleStagedFilePut(
+  request: Request,
+  env: CoordinatorEnv,
+): Promise<Response> {
+  if (request.method !== 'POST') {
+    return new Response('method not allowed', { status: 405 });
+  }
+  const url = new URL(request.url);
+  const rawKey = url.searchParams.get('key')?.trim() ?? '';
+  if (rawKey) {
+    const key = rawKey;
+    const contentType =
+      url.searchParams.get('contentType')?.trim() ||
+      'application/octet-stream';
+    const expectedBytes = Number(url.searchParams.get('bytes') ?? 'NaN');
+    if (!isAllowedStagedFileStorageKey(key)) {
+      return Response.json(
+        { error: 'invalid staged file key' },
+        { status: 400 },
+      );
+    }
+    if (!Number.isSafeInteger(expectedBytes) || expectedBytes < 0) {
+      return Response.json({ error: 'bytes is required' }, { status: 400 });
+    }
+    const existing = await headExistingStagedFile(env, key, expectedBytes);
+    if (existing.exists) {
+      console.info('[perf][coordinator.staged_file_put]', {
+        key,
+        bytes: expectedBytes,
+        headMs: existing.ms,
+        putMs: 0,
+        ms: existing.ms,
+        transport: 'raw',
+        skipped: true,
+      });
+      return Response.json({
+        ok: true,
+        key,
+        bytes: expectedBytes,
+        existed: true,
+        timingsMs: { head: existing.ms, put: 0 },
+      });
+    }
+    const readStartedAt = Date.now();
+    const bytes = new Uint8Array(await request.arrayBuffer());
+    const readMs = Date.now() - readStartedAt;
+    if (bytes.byteLength !== expectedBytes) {
+      return Response.json(
+        { error: 'staged file byte length mismatch' },
+        { status: 400 },
+      );
+    }
+    const putStartedAt = Date.now();
+    await env.PLAYS_BUCKET.put(key, bytes, {
+      httpMetadata: { contentType },
+    });
+    const putMs = Date.now() - putStartedAt;
+    console.info('[perf][coordinator.staged_file_put]', {
+      key,
+      bytes: bytes.byteLength,
+      readMs,
+      putMs,
+      ms: readMs + putMs,
+      transport: 'raw',
+    });
+    return Response.json({
+      ok: true,
+      key,
+      bytes: bytes.byteLength,
+      timingsMs: { read: readMs, put: putMs },
+    });
+  }
+  const body = (await request.json().catch(() => null)) as
+    | {
+        key?: unknown;
+        contentBase64?: unknown;
+        contentType?: unknown;
+        bytes?: unknown;
+      }
+    | null;
+  const key = typeof body?.key === 'string' ? body.key.trim() : '';
+  const contentBase64 =
+    typeof body?.contentBase64 === 'string' ? body.contentBase64 : '';
+  const contentType =
+    typeof body?.contentType === 'string' && body.contentType.trim()
+      ? body.contentType.trim()
+      : 'application/octet-stream';
+  const expectedBytes = typeof body?.bytes === 'number' ? body.bytes : NaN;
+  if (!isAllowedStagedFileStorageKey(key)) {
+    return Response.json(
+      { error: 'invalid staged file key' },
+      { status: 400 },
+    );
+  }
+  if (
+    !contentBase64 ||
+    !Number.isSafeInteger(expectedBytes) ||
+    expectedBytes < 0
+  ) {
+    return Response.json(
+      { error: 'contentBase64 and bytes are required' },
+      { status: 400 },
+    );
+  }
+  const existing = await headExistingStagedFile(env, key, expectedBytes);
+  if (existing.exists) {
+    console.info('[perf][coordinator.staged_file_put]', {
+      key,
+      bytes: expectedBytes,
+      headMs: existing.ms,
+      putMs: 0,
+      ms: existing.ms,
+      transport: 'base64',
+      skipped: true,
+    });
+    return Response.json({
+      ok: true,
+      key,
+      bytes: expectedBytes,
+      existed: true,
+      timingsMs: { head: existing.ms, put: 0 },
+    });
+  }
+  const decodeStartedAt = Date.now();
+  const bytes = decodeBase64ToUint8Array(contentBase64);
+  const decodeMs = Date.now() - decodeStartedAt;
+  if (bytes.byteLength !== expectedBytes) {
+    return Response.json(
+      { error: 'staged file byte length mismatch' },
+      { status: 400 },
+    );
+  }
+  const putStartedAt = Date.now();
+  await env.PLAYS_BUCKET.put(key, bytes, {
+    httpMetadata: { contentType },
+  });
+  const putMs = Date.now() - putStartedAt;
+  console.info('[perf][coordinator.staged_file_put]', {
+    key,
+    bytes: bytes.byteLength,
+    decodeMs,
+    putMs,
+    ms: decodeMs + putMs,
+  });
+  return Response.json({
+    ok: true,
+    key,
+    bytes: bytes.byteLength,
+    timingsMs: { decode: decodeMs, put: putMs },
+  });
+}
+
+async function headExistingStagedFile(
+  env: CoordinatorEnv,
+  key: string,
+  expectedBytes: number,
+): Promise<{ exists: boolean; ms: number }> {
+  const startedAt = Date.now();
+  const object = await env.PLAYS_BUCKET.head(key).catch(() => null);
+  const ms = Date.now() - startedAt;
+  if (!object) {
+    return { exists: false, ms };
+  }
+  if (typeof object.size === 'number' && object.size !== expectedBytes) {
+    return { exists: false, ms };
+  }
+  return { exists: true, ms };
+}
+
 async function handleCoordinatorWarmup(
   request: Request,
   env: CoordinatorEnv,
@@ -3329,6 +3982,10 @@ function makeCoordinatorControlBinding():
           runId: string,
           payload: CoordinatorPerfTracePayload,
         ): Promise<void>;
+        recordRunEvent(
+          runId: string,
+          event: CoordinatorRunEvent,
+        ): Promise<void>;
       };
     }
   | Record<string, never> {
@@ -3346,6 +4003,10 @@ function makeCoordinatorControlBinding():
         runId: string,
         payload: CoordinatorPerfTracePayload,
       ): Promise<void>;
+      recordRunEvent(
+        runId: string,
+        event: CoordinatorRunEvent,
+      ): Promise<void>;
     };
   };
   const ctor = exports.CoordinatorControl;