deepline 0.2.55 → 0.2.56

package/dist/cli/index.js

@@ -185,7 +185,7 @@ function configureProxyFromEnv() {
 configureProxyFromEnv();
 
 // src/cli/index.ts
-var import_promises8 = require("fs/promises");
+var import_promises9 = require("fs/promises");
 var import_node_path26 = require("path");
 var import_node_os19 = require("os");
 var import_commander4 = require("commander");
@@ -1044,7 +1044,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.55",
+  version: "0.2.56",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -1627,9 +1627,26 @@ var HttpClient = class {
         if (error instanceof AuthError || error instanceof DeeplineError) {
           throw error;
         }
-        lastError = error instanceof Error ? error : new Error(String(error));
+        const normalized = error instanceof Error ? error : new Error(String(error));
+        if (isAbortLikeError(normalized) && options?.signal?.aborted) {
+          throw new DeeplineError(
+            `Stream from ${this.config.baseUrl} was aborted by the caller.`,
+            void 0,
+            "ABORTED"
+          );
+        }
+        lastError = normalized;
       }
     }
+    if (lastError && isAbortLikeError(lastError)) {
+      throw new DeeplineError(
+        withCoworkNetworkHint(
+          `Unable to stream from ${this.config.baseUrl}. The remote stream was interrupted.`
+        ),
+        void 0,
+        "PLAY_STREAM_NETWORK_ABORTED"
+      );
+    }
     throw new DeeplineError(
       withCoworkNetworkHint(
         lastError?.message ? `Unable to stream from ${this.config.baseUrl}. ${lastError.message}` : `Unable to stream from ${this.config.baseUrl}.`
@@ -1892,6 +1909,9 @@ function streamReconnectDelayMs(attempt) {
   return Math.max(1, Math.floor(Math.random() * (cappedExponentialMs + 1)));
 }
 function isTransientPlayStreamError(error) {
+  if (error instanceof DeeplineError && error.code === "PLAY_STREAM_NETWORK_ABORTED") {
+    return true;
+  }
   if (error instanceof DeeplineError && typeof error.statusCode === "number") {
     return error.statusCode >= 500 && error.statusCode < 600;
   }
@@ -2044,6 +2064,7 @@ var RUNTIME_RECEIPT_OUTPUT_MAX_BYTES = 10 * 1024 * 1024;
 var RUNTIME_RECEIPT_COMPLETION_BUFFER_MAX_BYTES = 32 * 1024 * 1024;
 var RUNNER_TERMINAL_PUSH_MAX_BODY_BYTES = 16 * 1024 * 1024;
 var RUNTIME_RECEIPT_GATEWAY_BATCH_MAX_BYTES = 12 * 1024 * 1024;
+var RUNTIME_RECEIPT_WRITER_TARGET_BATCH_BYTES = 4 * 1024 * 1024;
 var RUNNER_POST_TERMINAL_DIAGNOSTIC_MAX_BYTES = 64 * 1024;
 
 // ../shared_libs/play-runtime/ledger-safe-payload.ts
@@ -4626,6 +4647,10 @@ var DeeplineClient = class {
         ...request.packagedFiles?.length ? { packagedFiles: request.packagedFiles } : {},
         ...request.force ? { force: true } : {},
         ...forceToolRefresh ? { forceToolRefresh: true } : {},
+        ...typeof request.maxConcurrentExternalCalls === "number" ? {
+          maxConcurrentExternalCalls: request.maxConcurrentExternalCalls
+        } : {},
+        ...typeof request.maxConcurrentRows === "number" ? { maxConcurrentRows: request.maxConcurrentRows } : {},
         ...typeof request.waitForCompletionMs === "number" ? { waitForCompletionMs: request.waitForCompletionMs } : {},
         // Profile selection is the API's job, not the CLI's. The server
         // defaults to absurd; callers normally omit this field.
@@ -4678,6 +4703,8 @@ var DeeplineClient = class {
       ...request.packagedFiles?.length ? { packagedFiles: request.packagedFiles } : {},
       ...request.force ? { force: true } : {},
       ...forceToolRefresh ? { forceToolRefresh: true } : {},
+      ...typeof request.maxConcurrentExternalCalls === "number" ? { maxConcurrentExternalCalls: request.maxConcurrentExternalCalls } : {},
+      ...typeof request.maxConcurrentRows === "number" ? { maxConcurrentRows: request.maxConcurrentRows } : {},
       ...typeof request.waitForCompletionMs === "number" ? { waitForCompletionMs: request.waitForCompletionMs } : {},
       ...request.profile ? { profile: request.profile } : {},
       ...integrationMode ? { integrationMode } : {},
@@ -8758,14 +8785,14 @@ function invoiceDateText(createdAt) {
 }
 function invoiceLine(entry, compact) {
   const amount = invoiceAmountText(entry.amount_cents, entry.currency);
-  const link = entry.url ?? "(no link)";
+  const link2 = entry.url ?? "(no link)";
   if (compact) {
     return [
       entry.id,
       invoiceDateText(entry.created_at),
       amount,
       entry.status,
-      link
+      link2
     ].join(" | ");
   }
   return [
@@ -8773,7 +8800,7 @@ function invoiceLine(entry, compact) {
     entry.description,
     amount,
     entry.status,
-    link
+    link2
   ].join(" | ");
 }
 async function handleInvoices(options) {
@@ -10917,7 +10944,7 @@ Examples:
 }
 
 // src/cli/commands/enrich.ts
-var import_promises5 = require("fs/promises");
+var import_promises6 = require("fs/promises");
 var import_node_os10 = require("os");
 var import_node_path15 = require("path");
 var import_commander2 = require("commander");
@@ -10925,6 +10952,7 @@ var import_commander2 = require("commander");
 // src/cli/commands/play.ts
 var import_node_crypto6 = require("crypto");
 var import_node_fs12 = require("fs");
+var import_promises5 = require("fs/promises");
 var import_node_path14 = require("path");
 var import_sync5 = require("csv-parse/sync");
 
@@ -17577,6 +17605,31 @@ ${hint}`;
   });
 }
 
+// ../shared_libs/play-runtime/governor/policy.ts
+var DEFAULT_MAX_CONCURRENT_EXTERNAL_CALLS = 64;
+var MAX_CONFIGURABLE_CONCURRENT_EXTERNAL_CALLS = 256;
+var MAX_CONFIGURABLE_CONCURRENT_ROWS = 1e3;
+function resolveMaxConcurrentExternalCalls(requested) {
+  if (requested === void 0 || requested === null) {
+    return DEFAULT_MAX_CONCURRENT_EXTERNAL_CALLS;
+  }
+  if (!Number.isSafeInteger(requested) || requested < 1 || requested > MAX_CONFIGURABLE_CONCURRENT_EXTERNAL_CALLS) {
+    throw new Error(
+      `maxConcurrentExternalCalls must be a whole number from 1 through ${MAX_CONFIGURABLE_CONCURRENT_EXTERNAL_CALLS}.`
+    );
+  }
+  return requested;
+}
+function resolveMaxConcurrentRows(requested) {
+  if (requested === void 0 || requested === null) return null;
+  if (!Number.isSafeInteger(requested) || requested < 1 || requested > MAX_CONFIGURABLE_CONCURRENT_ROWS) {
+    throw new Error(
+      `maxConcurrentRows must be a whole number from 1 through ${MAX_CONFIGURABLE_CONCURRENT_ROWS}.`
+    );
+  }
+  return requested;
+}
+
 // ../shared_libs/play-runtime/sandbox-runtime-limits.ts
 var PLAY_SANDBOX_SIZE_LIMITS = {
   standard: {
@@ -17801,6 +17854,7 @@ function stripLeadingTimestamp(line) {
 // ../shared_libs/play-runtime/fixture-behavior.ts
 var FIXTURE_BEHAVIOR_VERSION = 1;
 var FIXTURE_BEHAVIOR_RESPONSE_VERSION = 2;
+var FIXTURE_BEHAVIOR_REPLAY_VERSION = 3;
 var MAX_FIXTURE_RESPONSE_DELAY_SAMPLES = 256;
 var MAX_FIXTURE_RESPONSE_DELAY_MS = 8 * 6e4;
 var MAX_FIXTURE_RESPONSE_ERROR_MESSAGE_LENGTH = 500;
@@ -17812,7 +17866,11 @@ function validateFixtureBehavior(value) {
     return { ok: false, error: "fixtureBehavior must be a JSON object." };
   }
   const record = value;
-  const supportedKeys = record.version === FIXTURE_BEHAVIOR_RESPONSE_VERSION ? /* @__PURE__ */ new Set(["version", "responseSamples"]) : /* @__PURE__ */ new Set(["version", "responseDelaySamplesMs"]);
+  const supportedKeys = record.version === FIXTURE_BEHAVIOR_RESPONSE_VERSION || record.version === FIXTURE_BEHAVIOR_REPLAY_VERSION ? /* @__PURE__ */ new Set([
+    "version",
+    "responseSamples",
+    ...record.version === FIXTURE_BEHAVIOR_REPLAY_VERSION ? ["replayBundle"] : []
+  ]) : /* @__PURE__ */ new Set(["version", "responseDelaySamplesMs"]);
   const unknownKeys = Object.keys(record).filter(
     (key) => !supportedKeys.has(key)
   );
@@ -17822,13 +17880,13 @@ function validateFixtureBehavior(value) {
       error: `Unsupported fixtureBehavior field "${unknownKeys[0]}".`
     };
   }
-  if (record.version !== FIXTURE_BEHAVIOR_VERSION && record.version !== FIXTURE_BEHAVIOR_RESPONSE_VERSION) {
+  if (record.version !== FIXTURE_BEHAVIOR_VERSION && record.version !== FIXTURE_BEHAVIOR_RESPONSE_VERSION && record.version !== FIXTURE_BEHAVIOR_REPLAY_VERSION) {
     return {
       ok: false,
-      error: `fixtureBehavior.version must be ${FIXTURE_BEHAVIOR_VERSION} or ${FIXTURE_BEHAVIOR_RESPONSE_VERSION}.`
+      error: `fixtureBehavior.version must be ${FIXTURE_BEHAVIOR_VERSION} or ${FIXTURE_BEHAVIOR_RESPONSE_VERSION}, or ${FIXTURE_BEHAVIOR_REPLAY_VERSION}.`
     };
   }
-  if (record.version === FIXTURE_BEHAVIOR_RESPONSE_VERSION) {
+  if (record.version === FIXTURE_BEHAVIOR_RESPONSE_VERSION || record.version === FIXTURE_BEHAVIOR_REPLAY_VERSION) {
     if (!Array.isArray(record.responseSamples) || record.responseSamples.length === 0 || record.responseSamples.length > MAX_FIXTURE_RESPONSE_DELAY_SAMPLES) {
       return {
         ok: false,
@@ -17935,6 +17993,72 @@ function validateFixtureBehavior(value) {
         ...httpError ? { httpError } : {}
       });
     }
+    let replayBundle;
+    if (record.version === FIXTURE_BEHAVIOR_REPLAY_VERSION) {
+      if (!record.replayBundle || typeof record.replayBundle !== "object" || Array.isArray(record.replayBundle)) {
+        return {
+          ok: false,
+          error: "fixtureBehavior.replayBundle must be an object."
+        };
+      }
+      const replay = record.replayBundle;
+      const replayUnknownKeys = Object.keys(replay).filter(
+        (key) => key !== "bundleId" && key !== "manifestSha256" && key !== "syntheticFallbackToolIds"
+      );
+      if (replayUnknownKeys.length > 0) {
+        return {
+          ok: false,
+          error: `Unsupported fixtureBehavior.replayBundle field "${replayUnknownKeys[0]}".`
+        };
+      }
+      const digestPattern = /^[a-f0-9]{64}$/;
+      if (typeof replay.bundleId !== "string" || !digestPattern.test(replay.bundleId)) {
+        return {
+          ok: false,
+          error: "fixtureBehavior.replayBundle.bundleId must be a lowercase SHA-256 digest."
+        };
+      }
+      if (typeof replay.manifestSha256 !== "string" || !digestPattern.test(replay.manifestSha256)) {
+        return {
+          ok: false,
+          error: "fixtureBehavior.replayBundle.manifestSha256 must be a lowercase SHA-256 digest."
+        };
+      }
+      let syntheticFallbackToolIds;
+      if (replay.syntheticFallbackToolIds !== void 0) {
+        if (!Array.isArray(replay.syntheticFallbackToolIds) || replay.syntheticFallbackToolIds.length === 0 || replay.syntheticFallbackToolIds.length > 32) {
+          return {
+            ok: false,
+            error: "fixtureBehavior.replayBundle.syntheticFallbackToolIds must contain 1-32 tool ids."
+          };
+        }
+        syntheticFallbackToolIds = [];
+        for (const rawToolId of replay.syntheticFallbackToolIds) {
+          if (typeof rawToolId !== "string" || rawToolId !== rawToolId.trim().toLowerCase() || !/^[a-z0-9][a-z0-9_.-]*$/.test(rawToolId) || rawToolId.length > 250 || syntheticFallbackToolIds.includes(rawToolId)) {
+            return {
+              ok: false,
+              error: "fixtureBehavior.replayBundle.syntheticFallbackToolIds contains an invalid tool id."
+            };
+          }
+          syntheticFallbackToolIds.push(rawToolId);
+        }
+      }
+      replayBundle = {
+        bundleId: replay.bundleId,
+        manifestSha256: replay.manifestSha256,
+        ...syntheticFallbackToolIds ? { syntheticFallbackToolIds } : {}
+      };
+    }
+    if (record.version === FIXTURE_BEHAVIOR_REPLAY_VERSION) {
+      return {
+        ok: true,
+        behavior: {
+          version: FIXTURE_BEHAVIOR_REPLAY_VERSION,
+          responseSamples: samples2,
+          replayBundle
+        }
+      };
+    }
     return {
       ok: true,
       behavior: {
@@ -18027,6 +18151,114 @@ var PLAY_RUN_RESERVED_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--debug-map-latency",
   "--debug-fixture-provider-pacing"
 ]);
+async function pathExistsIncludingSymlink(path) {
+  try {
+    await (0, import_promises5.lstat)(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+function runIdFileTempPath(destination) {
+  return (0, import_node_path14.join)(
+    (0, import_node_path14.dirname)(destination),
+    `.${(0, import_node_path14.basename)(destination)}.${process.pid}.${(0, import_node_crypto6.randomUUID)()}.tmp`
+  );
+}
+async function removeRunIdTempFile(path) {
+  try {
+    await (0, import_promises5.unlink)(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+async function preflightRunIdFile(path) {
+  const destination = (0, import_node_path14.resolve)(path);
+  if (await pathExistsIncludingSymlink(destination)) {
+    throw new Error(
+      `--run-id-file destination already exists: ${destination}. Choose a new path so this run cannot overwrite another run identity.`
+    );
+  }
+  const tempPath = runIdFileTempPath(destination);
+  let handle = null;
+  try {
+    handle = await (0, import_promises5.open)(tempPath, "wx", 384);
+    await handle.sync();
+  } catch (error) {
+    throw new Error(
+      `Cannot write --run-id-file destination ${destination}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  } finally {
+    await handle?.close();
+    await removeRunIdTempFile(tempPath);
+  }
+  return destination;
+}
+async function readRunIdFile(destination) {
+  if (!await pathExistsIncludingSymlink(destination)) {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(await (0, import_promises5.readFile)(destination, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `--run-id-file destination contains invalid JSON: ${destination}. Refusing to overwrite it (${error instanceof Error ? error.message : String(error)}).`
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || parsed.version !== 1 || typeof parsed.runId !== "string" || !parsed.runId) {
+    throw new Error(
+      `--run-id-file destination has an unsupported identity record: ${destination}. Refusing to overwrite it.`
+    );
+  }
+  return parsed;
+}
+async function writePlayRunIdFile(destination, runId) {
+  const existing = await readRunIdFile(destination);
+  if (existing) {
+    if (existing.runId === runId) return;
+    throw new Error(
+      `--run-id-file destination already records run ${existing.runId}; refusing to replace it with ${runId}: ${destination}`
+    );
+  }
+  const tempPath = runIdFileTempPath(destination);
+  let handle = null;
+  try {
+    handle = await (0, import_promises5.open)(tempPath, "wx", 384);
+    await handle.writeFile(
+      `${JSON.stringify({ version: 1, runId })}
+`,
+      "utf8"
+    );
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    try {
+      await (0, import_promises5.link)(tempPath, destination);
+      const directory = await (0, import_promises5.open)((0, import_node_path14.dirname)(destination), "r");
+      try {
+        await directory.sync();
+      } finally {
+        await directory.close();
+      }
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const raced = await readRunIdFile(destination);
+      if (raced?.runId === runId) return;
+      throw new Error(
+        `--run-id-file destination already records run ${raced?.runId ?? "<invalid>"}; refusing to replace it with ${runId}: ${destination}`
+      );
+    }
+  } finally {
+    await handle?.close();
+    await removeRunIdTempFile(tempPath);
+  }
+}
 function traceCliSync(phase, fields, run) {
   const startedAt = Date.now();
   try {
@@ -19431,8 +19663,8 @@ function buildPlayDashboardUrl(baseUrl, playName) {
   const encodedPlayName = encodeURIComponent(playName);
   return `${trimmedBase}/dashboard/plays/${encodedPlayName}`;
 }
-function openPlayDashboard(dashboardUrl, open) {
-  if (open && dashboardUrl) {
+function openPlayDashboard(dashboardUrl, open2) {
+  if (open2 && dashboardUrl) {
     openInBrowser(dashboardUrl);
   }
 }
@@ -19468,9 +19700,11 @@ function assertPlayWaitNotTimedOut(input2) {
     );
   }
 }
+var PLAY_DURABLE_STATUS_PROBE_INTERVAL_MS = 15e3;
 async function waitForPlayCompletionByStream(input2) {
   let lastPhase = null;
   let reconnectAttempt = 0;
+  let nextDurableProbeAt = Date.now() + PLAY_DURABLE_STATUS_PROBE_INTERVAL_MS;
   const withDashboardUrl = (status) => input2.dashboardUrl ? { ...status, dashboardUrl: input2.dashboardUrl } : status;
   const remainingWaitMs = () => input2.waitTimeoutMs === null ? null : input2.waitTimeoutMs - (Date.now() - input2.startedAt);
   const fetchTerminalStatus = async () => {
@@ -19489,6 +19723,14 @@ async function waitForPlayCompletionByStream(input2) {
   };
   const handleLiveEvent = async (event) => {
     assertPlayWaitNotTimedOut({ ...input2, lastPhase });
+    const now = Date.now();
+    if (now >= nextDurableProbeAt) {
+      nextDurableProbeAt = now + PLAY_DURABLE_STATUS_PROBE_INTERVAL_MS;
+      const durableTerminal = await fetchTerminalStatus();
+      if (durableTerminal) {
+        return durableTerminal;
+      }
+    }
     const phase = describeLiveEventPhase(event);
     if (phase) {
       lastPhase = phase;
@@ -19737,7 +19979,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
         lastKnownWorkflowId = eventRunId;
         firstRunIdMs ??= Date.now() - startedAt;
         if (runStartedNow) {
-          input2.onRunStarted?.(eventRunId);
+          await input2.onRunStarted?.(eventRunId);
         }
       }
       if (eventConfirmsPlayRunLaunch(event) && eventRunId === lastKnownWorkflowId) {
@@ -21016,6 +21258,15 @@ function buildOrdinaryPlayRunCommand(options, resolvedRevisionId) {
   }
   if (options.profile)
     parts.push("--profile", shellSingleQuote(options.profile));
+  if (options.maxConcurrentExternalCalls !== null) {
+    parts.push(
+      "--max-concurrent-external-calls",
+      String(options.maxConcurrentExternalCalls)
+    );
+  }
+  if (options.maxConcurrentRows !== null) {
+    parts.push("--max-concurrent-rows", String(options.maxConcurrentRows));
+  }
   const pinnedRevisionId = options.target.kind === "name" ? resolvedRevisionId ?? options.revisionId : null;
   if (pinnedRevisionId) {
     parts.push("--revision-id", shellSingleQuote(pinnedRevisionId));
@@ -21885,7 +22136,7 @@ function writeStartedPlayRun(input2) {
   );
 }
 function parsePlayRunOptions(args) {
-  const usage = "Usage: deepline plays run <play-name> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--open] [--full] [--<input> value]\n       deepline plays run <play-file.ts> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--open] [--full] [--<input> value]\n       deepline plays run --file <play-file.ts> [--input '{...}'] [--profile <id>] [--no-wait] [--tail-timeout-ms 30000] [--force] [--open] [--full] [--<input> value]\n       deepline plays run --name <name> [--input '{...}'] [--profile <id>] [--live|--latest|--revision-id <id>] [--no-wait] [--tail-timeout-ms 30000] [--force] [--open] [--json] [--full] [--<input> value]\n       Runs use the Absurd CJS runtime.\n       Unknown --<input> value flags, such as --limit 5, are passed into play input.\nRun `deepline plays run --help` for idempotent call caching and ctx.dataset guidance.";
+  const usage = "Usage: deepline plays run <play-name> [--input '{...}'] [--run-id-file <path>] [--no-wait] [--tail-timeout-ms 30000] [--force] [--open] [--full] [--<input> value]\n       deepline plays run <play-file.ts> [--input '{...}'] [--run-id-file <path>] [--no-wait] [--tail-timeout-ms 30000] [--force] [--open] [--full] [--<input> value]\n       deepline plays run --file <play-file.ts> [--input '{...}'] [--profile <id>] [--run-id-file <path>] [--no-wait] [--tail-timeout-ms 30000] [--force] [--open] [--full] [--<input> value]\n       deepline plays run --name <name> [--input '{...}'] [--profile <id>] [--live|--latest|--revision-id <id>] [--run-id-file <path>] [--no-wait] [--tail-timeout-ms 30000] [--force] [--open] [--json] [--full] [--<input> value]\n       Runs use the Absurd CJS runtime.\n       Unknown --<input> value flags, such as --limit 5, are passed into play input.\nRun `deepline plays run --help` for idempotent call caching and ctx.dataset guidance.";
   let filePath = null;
   let playName = null;
   let input2 = null;
@@ -21896,15 +22147,18 @@ function parsePlayRunOptions(args) {
   const fullJson = args.includes("--full");
   const emitLogs = !jsonOutput || args.includes("--logs");
   const force = args.includes("--force");
-  const open = args.includes("--open");
+  const open2 = args.includes("--open");
   const debugMapLatency = args.includes("--debug-map-latency");
   const debugFixtureProviderPacing = args.includes(
     "--debug-fixture-provider-pacing"
   );
   const verboseLogs = args.includes("--logs") || debugMapLatency;
   let waitTimeoutMs = null;
+  let maxConcurrentExternalCalls = null;
+  let maxConcurrentRows = null;
   let profile = null;
   let fixtureBehavior = null;
+  let runIdFile = null;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--file" && args[index + 1]) {
@@ -21919,6 +22173,23 @@ function parsePlayRunOptions(args) {
       input2 = parseJsonInput(args[++index]);
       continue;
     }
+    if (arg === "--run-id-file") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--run-id-file requires a destination path.");
+      }
+      runIdFile = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--run-id-file=")) {
+      const value = arg.slice("--run-id-file=".length);
+      if (!value) {
+        throw new Error("--run-id-file requires a destination path.");
+      }
+      runIdFile = value;
+      continue;
+    }
     if (arg === "--revision-id" && args[index + 1]) {
       revisionId = args[++index];
       continue;
@@ -21933,6 +22204,41 @@ function parsePlayRunOptions(args) {
       index += 1;
       continue;
     }
+    if (arg === "--max-concurrent-external-calls") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error(
+          "--max-concurrent-external-calls requires a whole number."
+        );
+      }
+      if (!/^[1-9]\d*$/.test(value)) {
+        throw new Error(
+          "--max-concurrent-external-calls requires a positive whole number."
+        );
+      }
+      maxConcurrentExternalCalls = parsePositiveInteger3(
+        value,
+        "--max-concurrent-external-calls"
+      );
+      resolveMaxConcurrentExternalCalls(maxConcurrentExternalCalls);
+      index += 1;
+      continue;
+    }
+    if (arg === "--max-concurrent-rows") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--max-concurrent-rows requires a whole number.");
+      }
+      if (!/^[1-9]\d*$/.test(value)) {
+        throw new Error(
+          "--max-concurrent-rows requires a positive whole number."
+        );
+      }
+      maxConcurrentRows = parsePositiveInteger3(value, "--max-concurrent-rows");
+      resolveMaxConcurrentRows(maxConcurrentRows);
+      index += 1;
+      continue;
+    }
     if (arg === "--fixture-behavior") {
       const value = args[index + 1];
       if (!value) {
@@ -22043,11 +22349,14 @@ function parsePlayRunOptions(args) {
     fullJson,
     waitTimeoutMs,
     force,
-    open,
+    maxConcurrentExternalCalls,
+    maxConcurrentRows,
+    open: open2,
     profile,
     debugMapLatency,
     debugFixtureProviderPacing,
-    fixtureBehavior
+    fixtureBehavior,
+    runIdFile
   };
 }
 function parsePlayCheckOptions(args) {
@@ -22730,6 +23039,8 @@ async function handleFileBackedRun(options, hooks) {
     ...stagedFileInputs.inputFile ? { inputFile: stagedFileInputs.inputFile } : {},
     ...stagedFileInputs.packagedFiles.length ? { packagedFiles: stagedFileInputs.packagedFiles } : {},
     ...options.force ? { force: true } : {},
+    ...options.maxConcurrentExternalCalls !== null ? { maxConcurrentExternalCalls: options.maxConcurrentExternalCalls } : {},
+    ...options.maxConcurrentRows !== null ? { maxConcurrentRows: options.maxConcurrentRows } : {},
     ...options.profile ? { profile: options.profile } : {},
     ...Object.keys(testPolicyOverrides).length > 0 ? { testPolicyOverrides } : {},
     ...integrationMode ? { integrationMode } : {},
@@ -22790,6 +23101,7 @@ async function handleFileBackedRun(options, hooks) {
       throw await normalizePlayStartError(client2, error, playName);
     })
   );
+  await hooks?.onRunStarted?.(started.workflowId);
   const resolvedDashboardUrl = buildPlayDashboardUrl(client2.baseUrl, playName);
   openPlayDashboard(resolvedDashboardUrl, options.open);
   progress.phase("started run");
@@ -22910,6 +23222,8 @@ async function handleNamedRun(options, hooks) {
     ...stagedFileInputs.inputFile ? { inputFile: stagedFileInputs.inputFile } : {},
     ...stagedFileInputs.packagedFiles.length ? { packagedFiles: stagedFileInputs.packagedFiles } : {},
     ...options.force ? { force: true } : {},
+    ...options.maxConcurrentExternalCalls !== null ? { maxConcurrentExternalCalls: options.maxConcurrentExternalCalls } : {},
+    ...options.maxConcurrentRows !== null ? { maxConcurrentRows: options.maxConcurrentRows } : {},
     ...options.profile ? { profile: options.profile } : {},
     ...Object.keys(testPolicyOverrides).length > 0 ? { testPolicyOverrides } : {},
     ...integrationMode ? { integrationMode } : {},
@@ -22975,6 +23289,7 @@ async function handleNamedRun(options, hooks) {
       });
     })
   );
+  await hooks?.onRunStarted?.(started.workflowId);
   const resolvedDashboardUrl = buildPlayDashboardUrl(client2.baseUrl, playName);
   openPlayDashboard(resolvedDashboardUrl, options.open);
   progress.phase("started run");
@@ -22991,10 +23306,28 @@ async function handleNamedRun(options, hooks) {
   return 0;
 }
 async function handlePlayRun(args, hooks) {
-  const options = parsePlayRunOptions(args);
+  const parsedOptions = parsePlayRunOptions(args);
+  const options = parsedOptions.runIdFile ? {
+    ...parsedOptions,
+    runIdFile: await preflightRunIdFile(parsedOptions.runIdFile)
+  } : parsedOptions;
+  const runHooks = options.runIdFile ? {
+    ...hooks,
+    onRunStarted: async (runId) => {
+      try {
+        await writePlayRunIdFile(options.runIdFile, runId);
+      } catch (error) {
+        throw new Error(
+          `Run ${runId} was accepted, but its identity could not be persisted to ${options.runIdFile}: ${error instanceof Error ? error.message : String(error)}. Inspect it with 'deepline runs get ${runId} --full --json'; do not submit a replacement run.`,
+          { cause: error }
+        );
+      }
+      await hooks?.onRunStarted?.(runId);
+    }
+  } : hooks;
   if (options.target.kind === "file") {
     if (isFileTarget(options.target.path)) {
-      return handleFileBackedRun(options, hooks);
+      return handleFileBackedRun(options, runHooks);
     }
     const resolved = (0, import_node_path14.resolve)(options.target.path);
     console.error(`File not found: ${resolved}`);
@@ -23016,7 +23349,7 @@ async function handlePlayRun(args, hooks) {
     }
     return 1;
   }
-  return handleNamedRun(options, hooks);
+  return handleNamedRun(options, runHooks);
 }
 function parseRunIdPositional(args, usage) {
   for (let index = 0; index < args.length; index += 1) {
@@ -24344,10 +24677,18 @@ Notes:
   next commands. --watch and --wait are accepted compatibility aliases for the
   default behavior. Use --no-wait only when you intentionally want
   a fire-and-forget run id.
+  --run-id-file writes the durable run id to a versioned JSON file as soon as
+  the server accepts the run. The destination must not already exist.
   The play page URL is printed when the run starts. Pass --open to open it in a browser.
   Concurrent runs for the same play are allowed.
   --force starts a fresh run graph without refreshing completed provider calls.
   It does not cancel active sibling runs.
+  --max-concurrent-external-calls controls the per-run provider-tool/ctx.fetch
+  resident-work ceiling. Default: ${DEFAULT_MAX_CONCURRENT_EXTERNAL_CALLS}; accepted range: 1-${MAX_CONFIGURABLE_CONCURRENT_EXTERNAL_CALLS}.
+  Provider pacing and sandbox memory limits still apply.
+  --max-concurrent-rows sets the run-wide default and ceiling for live map row
+  resolvers. Accepted range: 1-${MAX_CONFIGURABLE_CONCURRENT_ROWS}. The runtime
+  may lower it when source-row size exceeds the active-row memory budget.
   This command starts cloud work and may spend Deepline credits through tool calls.
 
 Idempotent execution:
@@ -24383,8 +24724,10 @@ Idempotent execution:
 Examples:
   deepline plays run prebuilt/person-linkedin-to-email --input '{"linkedin_url":"..."}'
   deepline plays run long-background-play --no-wait
+  deepline plays run long-background-play --run-id-file ./run-id.json
   deepline plays run my.play.ts --input '{"domain":"stripe.com"}'
   deepline plays run my.play.ts --profile absurd
+  deepline plays run my.play.ts --max-concurrent-external-calls 20
   deepline plays run my.play.ts --input @input.json --json
   deepline plays run cto-search.play.ts --limit 5
   deepline runs export <run-id> --out output.csv
@@ -24400,9 +24743,18 @@ Examples:
     "--fixture-behavior <json>",
     "Internal/testing: fixture response behavior JSON object or @file path"
   ).option("--watch", "Compatibility alias; run waits by default").option("--wait", "Compatibility alias; run waits by default").option("--no-wait", "Start the run and return immediately").option(
+    "--run-id-file <path>",
+    "Atomically write the accepted run id to a new JSON file"
+  ).option(
     "--logs",
     "When output is non-interactive, stream play logs to stderr while waiting"
-  ).option("--tail-timeout-ms <ms>", "Timeout while watching the run stream").option("--force", "Start a fresh run graph").option("--open", "Open the play page in a browser after the run starts").option(
+  ).option("--tail-timeout-ms <ms>", "Timeout while watching the run stream").option("--force", "Start a fresh run graph").option(
+    "--max-concurrent-external-calls <count>",
+    `Concurrent provider-tool and ctx.fetch executions (${DEFAULT_MAX_CONCURRENT_EXTERNAL_CALLS} default, max ${MAX_CONFIGURABLE_CONCURRENT_EXTERNAL_CALLS})`
+  ).option(
+    "--max-concurrent-rows <count>",
+    `Run-wide dataset map row resolver ceiling (max ${MAX_CONFIGURABLE_CONCURRENT_ROWS})`
+  ).option("--open", "Open the play page in a browser after the run starts").option(
     "--debug-map-latency",
     "Internal diagnostics: emit one aggregate latency profile per dataset map"
   ).option(
@@ -24441,10 +24793,16 @@ Pass-through input flags:
       ...options.profile ? ["--profile", options.profile] : [],
       ...options.fixtureBehavior ? ["--fixture-behavior", options.fixtureBehavior] : [],
       ...options.wait === false ? ["--no-wait"] : [],
+      ...options.runIdFile ? ["--run-id-file", options.runIdFile] : [],
       ...options.watch || options.wait ? ["--watch"] : [],
       ...options.logs ? ["--logs"] : [],
       ...options.tailTimeoutMs ? ["--tail-timeout-ms", options.tailTimeoutMs] : [],
       ...options.force ? ["--force"] : [],
+      ...options.maxConcurrentExternalCalls ? [
+        "--max-concurrent-external-calls",
+        options.maxConcurrentExternalCalls
+      ] : [],
+      ...options.maxConcurrentRows ? ["--max-concurrent-rows", options.maxConcurrentRows] : [],
       ...options.open ? ["--open"] : [],
       ...options.debugMapLatency ? ["--debug-map-latency"] : [],
       ...options.debugFixtureProviderPacing ? ["--debug-fixture-provider-pacing"] : [],
@@ -26833,7 +27191,7 @@ async function readAtFileReference(value, argumentName, strip = true) {
     throw new Error(`Invalid ${argumentName} value: empty @file path.`);
   }
   try {
-    const text = await (0, import_promises5.readFile)(filePath, "utf8");
+    const text = await (0, import_promises6.readFile)(filePath, "utf8");
     const normalized = text.replace(/^\uFEFF/, "");
     return strip ? normalized.trim() : normalized;
   } catch (error) {
@@ -27131,7 +27489,7 @@ async function buildPlanArgs(args) {
 async function assertInputCsvExists(inputCsv) {
   const path = (0, import_node_path15.resolve)(inputCsv);
   try {
-    const info = await (0, import_promises5.stat)(path);
+    const info = await (0, import_promises6.stat)(path);
     if (info.isFile()) {
       return;
     }
@@ -27152,8 +27510,8 @@ async function assertSafeOutputPath(inputCsv, outputPath) {
   }
   try {
     const [inputInfo, outputInfo] = await Promise.all([
-      (0, import_promises5.stat)(input2),
-      (0, import_promises5.stat)(output2)
+      (0, import_promises6.stat)(input2),
+      (0, import_promises6.stat)(output2)
     ]);
     if (inputInfo.dev === outputInfo.dev && inputInfo.ino === outputInfo.ino) {
       throw new Error(
@@ -27173,7 +27531,7 @@ async function assertSafeOutputPath(inputCsv, outputPath) {
 }
 async function regularFileExists(path) {
   try {
-    const info = await (0, import_promises5.stat)((0, import_node_path15.resolve)(path));
+    const info = await (0, import_promises6.stat)((0, import_node_path15.resolve)(path));
     return info.isFile();
   } catch (error) {
     const code = error && typeof error === "object" ? error.code : void 0;
@@ -27184,7 +27542,7 @@ async function regularFileExists(path) {
   }
 }
 async function readConfig(path) {
-  const source = await (0, import_promises5.readFile)((0, import_node_path15.resolve)(path), "utf8");
+  const source = await (0, import_promises6.readFile)((0, import_node_path15.resolve)(path), "utf8");
   let parsed;
   try {
     parsed = JSON.parse(source);
@@ -27605,7 +27963,7 @@ async function writeOutputCsv(outputPath, status, options) {
     ]),
     options?.config
   );
-  await (0, import_promises5.writeFile)(
+  await (0, import_promises6.writeFile)(
     (0, import_node_path15.resolve)(outputPath),
     csvStringFromRows(merged.rows, columns),
     "utf8"
@@ -29285,7 +29643,7 @@ async function persistEnrichFailureReport(input2) {
   }
   const stateDir = (0, import_node_path15.join)((0, import_node_os10.homedir)(), ".local", "deepline", "runtime", "state");
   const reportPrefix = input2.jobs.length > 0 ? "run-block-failures" : "enrich-issues";
-  await (0, import_promises5.mkdir)(stateDir, { recursive: true });
+  await (0, import_promises6.mkdir)(stateDir, { recursive: true });
   const reportPath = (0, import_node_path15.join)(
     stateDir,
     `${reportPrefix}-${Math.floor(Date.now() / 1e3)}-${process.pid}.json`
@@ -29311,7 +29669,7 @@ async function persistEnrichFailureReport(input2) {
   if (input2.rows.rowStart !== null && input2.rows.rowEnd !== null) {
     report.rows = { start: input2.rows.rowStart, end: input2.rows.rowEnd };
   }
-  await (0, import_promises5.writeFile)(reportPath, `${JSON.stringify(report, null, 2)}
+  await (0, import_promises6.writeFile)(reportPath, `${JSON.stringify(report, null, 2)}
 `, "utf8");
   return reportPath;
 }
@@ -30214,13 +30572,13 @@ function registerEnrichCommand(program) {
       sdkEnrichTelemetryCompleted = true;
       await completeSdkEnrichTelemetry(sdkEnrichTelemetry, input2);
     };
-    const tempDir = await (0, import_promises5.mkdtemp)((0, import_node_path15.join)((0, import_node_os10.tmpdir)(), "deepline-enrich-play-"));
+    const tempDir = await (0, import_promises6.mkdtemp)((0, import_node_path15.join)((0, import_node_os10.tmpdir)(), "deepline-enrich-play-"));
     await emitSdkEnrichTelemetry(sdkEnrichTelemetry, "enrich_started");
     const tempPlay = (0, import_node_path15.join)(tempDir, "deepline-enrich.play.ts");
     let inPlaceTempDir = null;
     let inPlaceTempOutputPath = null;
     const inPlaceFinalOutputPath = options.inPlace ? (0, import_node_path15.resolve)(inputCsv) : null;
-    const inPlaceCommitOutputPath = options.inPlace ? (await (0, import_promises5.lstat)(inputCsv)).isSymbolicLink() ? await (0, import_promises5.realpath)(inputCsv) : inPlaceFinalOutputPath : null;
+    const inPlaceCommitOutputPath = options.inPlace ? (await (0, import_promises6.lstat)(inputCsv)).isSymbolicLink() ? await (0, import_promises6.realpath)(inputCsv) : inPlaceFinalOutputPath : null;
     const failureReportOutputPath = options.inPlace ? inPlaceFinalOutputPath : null;
     const enrichIssueFollowUpOutputPath = options.inPlace && inPlaceFinalOutputPath ? sidecarEnrichRowsExportPath(inPlaceFinalOutputPath) : null;
     let activeRunId2 = null;
@@ -30241,16 +30599,16 @@ function registerEnrichCommand(program) {
         return;
       }
       if (inPlaceTempDir) {
-        await (0, import_promises5.rm)(inPlaceTempDir, { recursive: true, force: true });
+        await (0, import_promises6.rm)(inPlaceTempDir, { recursive: true, force: true });
       }
-      inPlaceTempDir = await (0, import_promises5.mkdtemp)(
+      inPlaceTempDir = await (0, import_promises6.mkdtemp)(
         (0, import_node_path15.join)(
           (0, import_node_path15.dirname)(inPlaceCommitOutputPath ?? (0, import_node_path15.resolve)(inputCsv)),
           ".deepline-enrich-in-place-"
         )
       );
       inPlaceTempOutputPath = (0, import_node_path15.join)(inPlaceTempDir, "output.csv");
-      await (0, import_promises5.copyFile)((0, import_node_path15.resolve)(inputCsv), inPlaceTempOutputPath);
+      await (0, import_promises6.copyFile)((0, import_node_path15.resolve)(inputCsv), inPlaceTempOutputPath);
       outputPath = inPlaceTempOutputPath;
     };
     const commitInPlaceOutput = async (exportResult) => {
@@ -30258,12 +30616,12 @@ function registerEnrichCommand(program) {
         return exportResult;
       }
       const committedTempDir = inPlaceTempDir;
-      await (0, import_promises5.rename)(inPlaceTempOutputPath, inPlaceCommitOutputPath);
+      await (0, import_promises6.rename)(inPlaceTempOutputPath, inPlaceCommitOutputPath);
       inPlaceTempDir = null;
       inPlaceTempOutputPath = null;
       outputPath = inPlaceFinalOutputPath;
       if (committedTempDir) {
-        await (0, import_promises5.rm)(committedTempDir, { recursive: true, force: true });
+        await (0, import_promises6.rm)(committedTempDir, { recursive: true, force: true });
       }
       if (!exportResult) {
         return null;
@@ -30276,7 +30634,7 @@ function registerEnrichCommand(program) {
     try {
       process.once("SIGINT", onSigint);
       process.once("SIGTERM", onSigterm);
-      await (0, import_promises5.writeFile)(tempPlay, playSource, "utf8");
+      await (0, import_promises6.writeFile)(tempPlay, playSource, "utf8");
       if (options.inPlace) {
         await prepareInPlaceOutput();
       }
@@ -30470,11 +30828,11 @@ function registerEnrichCommand(program) {
       process.removeListener("SIGINT", onSigint);
       process.removeListener("SIGTERM", onSigterm);
       if (inPlaceTempDir) {
-        await (0, import_promises5.rm)(inPlaceTempDir, { recursive: true, force: true });
+        await (0, import_promises6.rm)(inPlaceTempDir, { recursive: true, force: true });
       } else if (inPlaceTempOutputPath) {
-        await (0, import_promises5.rm)(inPlaceTempOutputPath, { force: true });
+        await (0, import_promises6.rm)(inPlaceTempOutputPath, { force: true });
       }
-      await (0, import_promises5.rm)(tempDir, { recursive: true, force: true });
+      await (0, import_promises6.rm)(tempDir, { recursive: true, force: true });
     }
   });
 }
@@ -31366,7 +31724,7 @@ Examples:
 
 // src/cli/commands/monitors.ts
 var import_node_fs14 = require("fs");
-var import_promises6 = require("readline/promises");
+var import_promises7 = require("readline/promises");
 var JSON_OPTION_DESCRIPTION = "Emit JSON output. Also automatic when stdout is piped";
 function withJsonOption(command) {
   return command.option("--json", JSON_OPTION_DESCRIPTION);
@@ -32135,7 +32493,7 @@ async function handleMonitorsValidate(key, options) {
   if (result.valid === false) process.exitCode = 7;
 }
 async function confirmMonitorDelete(key, options) {
-  const rl = (0, import_promises6.createInterface)({
+  const rl = (0, import_promises7.createInterface)({
     input: process.stdin,
     output: process.stderr
   });
@@ -36156,7 +36514,7 @@ Examples:
 }
 
 // src/cli/commands/workflow.ts
-var import_promises7 = require("fs/promises");
+var import_promises8 = require("fs/promises");
 var import_node_path20 = require("path");
 
 // src/cli/workflow-to-play.ts
@@ -36366,7 +36724,7 @@ function readStatus(payload) {
 }
 async function readJsonOption(payload, file) {
   if (file) {
-    const raw = await (0, import_promises7.readFile)((0, import_node_path20.resolve)(file), "utf8");
+    const raw = await (0, import_promises8.readFile)((0, import_node_path20.resolve)(file), "utf8");
     return JSON.parse(raw);
   }
   if (payload) {
@@ -36401,8 +36759,8 @@ async function transformOne(api, workflowId, outDir, publish) {
       { workflowName: workflow.name, version: revision.version }
     );
     const file = (0, import_node_path20.join)((0, import_node_path20.resolve)(outDir), `${compiled.playName}.play.ts`);
-    await (0, import_promises7.mkdir)((0, import_node_path20.dirname)(file), { recursive: true });
-    await (0, import_promises7.writeFile)(file, compiled.sourceCode, "utf8");
+    await (0, import_promises8.mkdir)((0, import_node_path20.dirname)(file), { recursive: true });
+    await (0, import_promises8.writeFile)(file, compiled.sourceCode, "utf8");
     let published = false;
     if (publish) {
       const code = await handlePlayPublish([file]);
@@ -40477,10 +40835,10 @@ function topLevelCommandKnown(program, commandName) {
   );
 }
 async function runPlayRunnerHealthCheck() {
-  const dir = await (0, import_promises8.mkdtemp)((0, import_node_path26.join)((0, import_node_os19.tmpdir)(), "deepline-health-play-"));
+  const dir = await (0, import_promises9.mkdtemp)((0, import_node_path26.join)((0, import_node_os19.tmpdir)(), "deepline-health-play-"));
   const file = (0, import_node_path26.join)(dir, "health-check.play.ts");
   try {
-    await (0, import_promises8.writeFile)(
+    await (0, import_promises9.writeFile)(
       file,
       [
         "import { definePlay } from 'deepline';",
@@ -40529,7 +40887,7 @@ async function runPlayRunnerHealthCheck() {
       }
     };
   } finally {
-    await (0, import_promises8.rm)(dir, { recursive: true, force: true });
+    await (0, import_promises9.rm)(dir, { recursive: true, force: true });
   }
 }
 function pickString(value, ...keys) {