deepline 0.3.201 → 0.3.203

package/dist/cli/index.js

@@ -3051,7 +3051,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.201",
+  version: "0.3.203",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -3642,6 +3642,11 @@ var MAX_DIAGNOSTIC_HEADER_LENGTH = 120;
 var COWORK_NETWORK_HINT = "Claude Cowork appears to be running Deepline in a network-restricted sandbox. In Claude Desktop, open Settings > Capabilities, turn on Allow network egress, and set Domain allowlist to All domains for the Cowork session.";
 var REQUEST_TIMEOUT_MARKER = Symbol("deeplineRequestTimeout");
 var REQUEST_ABORT_MARKER = Symbol("deeplineRequestAbort");
+function requestCancelledError(signal) {
+  const error = withErrorCause(new Error("Request aborted"), signal.reason);
+  error[REQUEST_ABORT_MARKER] = true;
+  return error;
+}
 function normalizeRequestAbortError(error, input2) {
   const normalized = error instanceof Error ? error : new Error(String(error));
   const tagged = normalized;
@@ -3820,14 +3825,27 @@ var HttpClient = class {
     const candidateUrls = options?.exactUrlOnly ? [url] : buildCandidateUrls(url);
     let retryAfterDelayMs = null;
     const maxRetries = options?.maxRetries ?? this.config.maxRetries;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    requestAttempts: for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      if (options?.signal?.aborted) {
+        lastError = requestCancelledError(options.signal);
+        break;
+      }
       if (attempt > 0) {
         const backoffMs = Math.min(1e3 * Math.pow(2, attempt - 1), 3e4);
         const delayMs = retryAfterDelayMs === null ? backoffMs : Math.max(backoffMs, retryAfterDelayMs);
         retryAfterDelayMs = null;
-        await sleep(delayMs);
+        try {
+          await sleep(delayMs, options?.signal);
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+          break;
+        }
       }
       for (const candidateUrl of candidateUrls) {
+        if (options?.signal?.aborted) {
+          lastError = requestCancelledError(options.signal);
+          break requestAttempts;
+        }
         const controller = new AbortController();
         const timeoutMs = options?.timeout ?? this.config.timeout;
         let requestTimedOut = false;
@@ -3835,6 +3853,10 @@ var HttpClient = class {
           requestTimedOut = true;
           controller.abort();
         }, timeoutMs);
+        const abortRequest = () => controller.abort();
+        options?.signal?.addEventListener("abort", abortRequest, {
+          once: true
+        });
         try {
           const response = await fetch(candidateUrl, {
             method,
@@ -3847,8 +3869,8 @@ var HttpClient = class {
             clearTimeout(timeoutId);
             return null;
           }
-          clearTimeout(timeoutId);
           const body = await response.text();
+          clearTimeout(timeoutId);
           const parsed = parseResponseBody(body);
           const structuredToolError = options?.toolId && !response.ok ? deserializeToolExecutionFailure(
             apiErrorMessage(parsed, response.status),
@@ -3943,6 +3965,10 @@ var HttpClient = class {
           return parsed;
         } catch (error) {
           clearTimeout(timeoutId);
+          if (options?.signal?.aborted) {
+            lastError = requestCancelledError(options.signal);
+            break requestAttempts;
+          }
           if (error instanceof AuthError || error instanceof DeeplineError) {
             throw error;
           }
@@ -3954,6 +3980,9 @@ var HttpClient = class {
             timeoutMs,
             timedOut: requestTimedOut
           });
+        } finally {
+          clearTimeout(timeoutId);
+          options?.signal?.removeEventListener("abort", abortRequest);
         }
       }
       if (attempt < maxRetries) continue;
@@ -4282,8 +4311,23 @@ function decodeSseFrame(frame) {
   }
   return parsed;
 }
-function sleep(ms) {
-  return new Promise((resolve22) => setTimeout(resolve22, ms));
+function sleep(ms, signal) {
+  return new Promise((resolve22, reject) => {
+    if (signal?.aborted) {
+      reject(requestCancelledError(signal));
+      return;
+    }
+    const timeoutId = setTimeout(() => {
+      signal?.removeEventListener("abort", abort);
+      resolve22();
+    }, ms);
+    const abort = () => {
+      clearTimeout(timeoutId);
+      signal?.removeEventListener("abort", abort);
+      reject(requestCancelledError(signal));
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+  });
 }
 function withCoworkNetworkHint(message) {
   if (!isCoworkLikeSandbox2() || message.includes(COWORK_NETWORK_HINT)) {
@@ -5470,9 +5514,13 @@ function normalizePlayRunLedgerSnapshot(value, fallback) {
       tableNamespace: optionalString(rawDataset.tableNamespace) ?? datasetId,
       phase,
       persistedRows: Math.max(0, finiteNumber(rawDataset.persistedRows) ?? 0),
+      persistedRowsObserved: rawDataset.persistedRowsObserved === true,
       succeededRows: Math.max(0, finiteNumber(rawDataset.succeededRows) ?? 0),
+      succeededRowsObserved: rawDataset.succeededRowsObserved === true,
       failedRows: Math.max(0, finiteNumber(rawDataset.failedRows) ?? 0),
+      failedRowsObserved: rawDataset.failedRowsObserved === true,
       complete: rawDataset.complete === true,
+      completeObserved: rawDataset.completeObserved === true,
       // ADR 0019 birth survives the snapshot round trip. A partial record is
       // dropped rather than half-admitted, so a dataset either states where its
       // rows came from or says nothing.
@@ -7212,6 +7260,7 @@ var DeeplineClient = class _DeeplineClient {
     this.http = new HttpClient(this.config);
     this.runs = {
       get: (runId, options2) => this.getRunStatus(runId, options2),
+      status: (runId) => this.getRunLifecycleStatus(runId),
       list: (options2) => this.listRuns(options2),
       listPage: (options2) => this.listRunsPage(options2),
       tail: (runId, options2) => this.tailRun(runId, options2),
@@ -8624,6 +8673,13 @@ var DeeplineClient = class _DeeplineClient {
       }
     };
   }
+  /** Read only the bounded scalar projection; does not hydrate the run package. */
+  async getRunLifecycleStatus(runId) {
+    const response = await this.http.get(
+      `/api/v2/runs/${encodeURIComponent(runId)}/status`
+    );
+    return response;
+  }
   /**
    * List play runs using the public runs resource model.
    *
@@ -9017,7 +9073,8 @@ var DeeplineClient = class _DeeplineClient {
       params.set("rowMode", "all");
     }
     const result = await this.http.get(
-      `/api/v2/plays/${encodeURIComponent(input2.playName)}/sheet?${params.toString()}`
+      `/api/v2/plays/${encodeURIComponent(input2.playName)}/sheet?${params.toString()}`,
+      { signal: input2.signal }
     );
     const requestedRunId = input2.runId?.trim() || "";
     if (requestedRunId) {
@@ -20662,6 +20719,12 @@ 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;
+var MAX_FIXTURE_RETRY_AFTER_MS = 60 * 6e4;
+var FIXTURE_RATE_WINDOWS = [
+  { field: "requestsPerSecond", name: "rps", windowMs: 1e3 },
+  { field: "requestsPerMinute", name: "rpm", windowMs: 6e4 },
+  { field: "requestsPerHour", name: "rph", windowMs: 36e5 }
+];
 function validateFixtureBehavior(value) {
   if (value === void 0 || value === null) {
     return { ok: true, behavior: null };
@@ -20673,6 +20736,8 @@ function validateFixtureBehavior(value) {
   const supportedKeys = record3.version === FIXTURE_BEHAVIOR_RESPONSE_VERSION || record3.version === FIXTURE_BEHAVIOR_REPLAY_VERSION ? /* @__PURE__ */ new Set([
     "version",
     "responseSamples",
+    "transient429",
+    "sharedRateLimit",
     ...record3.version === FIXTURE_BEHAVIOR_REPLAY_VERSION ? ["replayBundle"] : []
   ]) : /* @__PURE__ */ new Set(["version", "responseDelaySamplesMs"]);
   const unknownKeys = Object.keys(record3).filter(
@@ -20769,7 +20834,7 @@ function validateFixtureBehavior(value) {
         }
         const error = sample.httpError;
         const errorUnknownKeys = Object.keys(error).filter(
-          (key) => key !== "status" && key !== "message"
+          (key) => key !== "status" && key !== "message" && key !== "retryAfterMs" && key !== "retryAfterFormat" && key !== "failuresBeforeSuccess"
         );
         if (errorUnknownKeys.length > 0) {
           return {
@@ -20789,7 +20854,33 @@ function validateFixtureBehavior(value) {
             error: `fixtureBehavior.responseSamples[${index}].httpError.message must contain 1-${MAX_FIXTURE_RESPONSE_ERROR_MESSAGE_LENGTH} characters.`
           };
         }
-        httpError = { status: error.status, message: error.message.trim() };
+        if (error.retryAfterMs !== void 0 && (error.status !== 429 || typeof error.retryAfterMs !== "number" || !Number.isSafeInteger(error.retryAfterMs) || error.retryAfterMs < 1 || error.retryAfterMs > MAX_FIXTURE_RETRY_AFTER_MS)) {
+          return {
+            ok: false,
+            error: `fixtureBehavior.responseSamples[${index}].httpError.retryAfterMs requires status 429 and an integer from 1 through ${MAX_FIXTURE_RETRY_AFTER_MS}.`
+          };
+        }
+        if (error.retryAfterFormat !== void 0 && (error.status !== 429 || error.retryAfterFormat !== "delta_seconds" && error.retryAfterFormat !== "http_date")) {
+          return {
+            ok: false,
+            error: `fixtureBehavior.responseSamples[${index}].httpError.retryAfterFormat requires status 429 and delta_seconds or http_date.`
+          };
+        }
+        if (error.failuresBeforeSuccess !== void 0 && (error.status !== 429 || typeof error.failuresBeforeSuccess !== "number" || !Number.isSafeInteger(error.failuresBeforeSuccess) || error.failuresBeforeSuccess < 1 || error.failuresBeforeSuccess > 20)) {
+          return {
+            ok: false,
+            error: `fixtureBehavior.responseSamples[${index}].httpError.failuresBeforeSuccess requires status 429 and an integer from 1 through 20.`
+          };
+        }
+        httpError = {
+          status: error.status,
+          message: error.message.trim(),
+          ...error.retryAfterMs !== void 0 ? { retryAfterMs: error.retryAfterMs } : {},
+          ...error.retryAfterFormat !== void 0 ? {
+            retryAfterFormat: error.retryAfterFormat
+          } : {},
+          ...error.failuresBeforeSuccess !== void 0 ? { failuresBeforeSuccess: error.failuresBeforeSuccess } : {}
+        };
       }
       samples2.push({
         delayMs: sample.delayMs,
@@ -20797,6 +20888,106 @@ function validateFixtureBehavior(value) {
         ...httpError ? { httpError } : {}
       });
     }
+    let sharedRateLimit;
+    if (record3.sharedRateLimit !== void 0) {
+      const plan = record3.sharedRateLimit;
+      if (!plan || typeof plan !== "object" || Array.isArray(plan)) {
+        return {
+          ok: false,
+          error: "fixtureBehavior.sharedRateLimit must be an object."
+        };
+      }
+      const planRecord = plan;
+      const entries = Object.entries(planRecord);
+      const boundaryAfterMs = planRecord.requestsPerHourBoundaryAfterMs;
+      const quotaEntries = entries.filter(
+        ([name]) => name !== "requestsPerHourBoundaryAfterMs"
+      );
+      if (quotaEntries.length === 0 || quotaEntries.some(
+        ([name, limit]) => !FIXTURE_RATE_WINDOWS.some((window) => window.field === name) || typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1
+      )) {
+        return {
+          ok: false,
+          error: "fixtureBehavior.sharedRateLimit requires positive integer requestsPerSecond, requestsPerMinute, or requestsPerHour quotas."
+        };
+      }
+      if (boundaryAfterMs !== void 0 && (planRecord.requestsPerHour === void 0 || typeof boundaryAfterMs !== "number" || !Number.isSafeInteger(boundaryAfterMs) || boundaryAfterMs < 1e3 || boundaryAfterMs > 3e5)) {
+        return {
+          ok: false,
+          error: "fixtureBehavior.sharedRateLimit.requestsPerHourBoundaryAfterMs requires requestsPerHour and an integer from 1000 through 300000."
+        };
+      }
+      sharedRateLimit = Object.fromEntries(entries);
+    }
+    let transient429;
+    if (record3.transient429 !== void 0) {
+      const selected = record3.transient429;
+      if (!selected || typeof selected !== "object" || Array.isArray(selected)) {
+        return {
+          ok: false,
+          error: "fixtureBehavior.transient429 must be an object."
+        };
+      }
+      const fault = selected;
+      const unknownFaultKeys = Object.keys(fault).filter(
+        (key) => key !== "everyNthCall" && key !== "retryAfterMs" && key !== "failuresBeforeSuccess" && key !== "when"
+      );
+      if (unknownFaultKeys.length > 0) {
+        return {
+          ok: false,
+          error: `Unsupported fixtureBehavior.transient429 field "${unknownFaultKeys[0]}".`
+        };
+      }
+      for (const [name, value2, max] of [
+        ["everyNthCall", fault.everyNthCall, 1e4],
+        ["retryAfterMs", fault.retryAfterMs, MAX_FIXTURE_RETRY_AFTER_MS],
+        ["failuresBeforeSuccess", fault.failuresBeforeSuccess, 20]
+      ]) {
+        if (typeof value2 !== "number" || !Number.isSafeInteger(value2) || value2 < 1 || value2 > max) {
+          return {
+            ok: false,
+            error: `fixtureBehavior.transient429.${name} must be an integer from 1 through ${max}.`
+          };
+        }
+      }
+      let when;
+      if (fault.when !== void 0) {
+        if (!fault.when || typeof fault.when !== "object" || Array.isArray(fault.when)) {
+          return {
+            ok: false,
+            error: "fixtureBehavior.transient429.when must be an object."
+          };
+        }
+        const condition = fault.when;
+        const unknownConditionKeys = Object.keys(condition).filter(
+          (key) => key !== "provider" && key !== "operation"
+        );
+        if (unknownConditionKeys.length > 0) {
+          return {
+            ok: false,
+            error: `Unsupported fixtureBehavior.transient429.when field "${unknownConditionKeys[0]}".`
+          };
+        }
+        const provider = normalizeFixtureScopeValue(condition.provider, 100);
+        const operation = normalizeFixtureScopeValue(condition.operation, 200);
+        if (provider.error || operation.error || !provider.value && !operation.value) {
+          return {
+            ok: false,
+            error: "fixtureBehavior.transient429.when must select a valid provider or operation."
+          };
+        }
+        when = {
+          ...provider.value ? { provider: provider.value } : {},
+          ...operation.value ? { operation: operation.value } : {}
+        };
+      }
+      transient429 = {
+        everyNthCall: fault.everyNthCall,
+        retryAfterMs: fault.retryAfterMs,
+        failuresBeforeSuccess: fault.failuresBeforeSuccess,
+        ...when ? { when } : {}
+      };
+    }
     let replayBundle;
     if (record3.version === FIXTURE_BEHAVIOR_REPLAY_VERSION) {
       if (!record3.replayBundle || typeof record3.replayBundle !== "object" || Array.isArray(record3.replayBundle)) {
@@ -20859,6 +21050,8 @@ function validateFixtureBehavior(value) {
         behavior: {
           version: FIXTURE_BEHAVIOR_REPLAY_VERSION,
           responseSamples: samples2,
+          ...transient429 ? { transient429 } : {},
+          ...sharedRateLimit ? { sharedRateLimit } : {},
           replayBundle
         }
       };
@@ -20867,7 +21060,9 @@ function validateFixtureBehavior(value) {
       ok: true,
       behavior: {
         version: FIXTURE_BEHAVIOR_RESPONSE_VERSION,
-        responseSamples: samples2
+        responseSamples: samples2,
+        ...transient429 ? { transient429 } : {},
+        ...sharedRateLimit ? { sharedRateLimit } : {}
       }
     };
   }
@@ -22751,43 +22946,52 @@ async function readRunIdFile(destination) {
   }
   return parsed;
 }
-async function writePlayRunIdFile(destination, runId) {
+async function writePlayRunIdFile(destination, runId, options = {}) {
   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}`
-    );
+    if (existing.runId !== runId) {
+      throw new Error(
+        `--run-id-file destination already records run ${existing.runId}; refusing to replace it with ${runId}: ${destination}`
+      );
+    }
+    if (!options.launchConfirmed || existing.launchConfirmed) return;
   }
   const tempPath = runIdFileTempPath(destination);
   let handle = null;
   try {
     handle = await (0, import_promises9.open)(tempPath, "wx", 384);
     await handle.writeFile(
-      `${JSON.stringify({ version: 1, runId })}
+      `${JSON.stringify({ version: 1, runId, ...options })}
 `,
       "utf8"
     );
     await handle.sync();
     await handle.close();
     handle = null;
-    try {
-      await (0, import_promises9.link)(tempPath, destination);
-      if (process.platform !== "win32") {
-        const directory = await (0, import_promises9.open)((0, import_node_path17.dirname)(destination), "r");
-        try {
-          await directory.sync();
-        } finally {
-          await directory.close();
+    if (existing) {
+      await (0, import_promises9.rename)(tempPath, destination);
+    } else {
+      try {
+        await (0, import_promises9.link)(tempPath, destination);
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        const raced = await readRunIdFile(destination);
+        if (raced?.runId !== runId) {
+          throw new Error(
+            `--run-id-file destination already records run ${raced?.runId ?? "<invalid>"}; refusing to replace it with ${runId}: ${destination}`
+          );
         }
+        if (!options.launchConfirmed || raced.launchConfirmed) return;
+        await (0, import_promises9.rename)(tempPath, destination);
+      }
+    }
+    if (process.platform !== "win32") {
+      const directory = await (0, import_promises9.open)((0, import_node_path17.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();
@@ -23844,6 +24048,16 @@ function getRunIdFromLiveEvent(event) {
 function eventConfirmsPlayRunLaunch(event) {
   return event.type === "play.run.status" && getEventPayload(event).launchConfirmed === true;
 }
+function statusProvesPlayRunExecution(status) {
+  return status === "waiting" || status === "completed";
+}
+function eventProvesPlayRunExecution(event) {
+  if (statusProvesPlayRunExecution(getStatusFromLiveEvent(event))) return true;
+  const payload = getEventPayload(event);
+  return Boolean(getStringField(payload, "stepId")) && (event.type === "play.step.progress" || event.type === "play.step.status" && ["running", "completed", "failed", "skipped"].includes(
+    getStringField(payload, "status") ?? ""
+  ));
+}
 function getStatusFromLiveEvent(event) {
   if (event.type !== "play.run.status" && event.type !== "play.run.snapshot" && event.type !== "play.run.final_status") {
     return null;
@@ -24320,6 +24534,12 @@ async function waitForPlayCompletionByStream(input2) {
   const durableStatusProbeIntervalMs = input2.durableStatusProbeIntervalMs ?? PLAY_DURABLE_STATUS_PROBE_INTERVAL_MS;
   let nextDurableProbeAt = Date.now() + durableStatusProbeIntervalMs;
   let durableStatusProbe = null;
+  let admissionConfirmed = false;
+  const confirmAdmission = async () => {
+    if (admissionConfirmed) return;
+    admissionConfirmed = true;
+    await input2.onRunAdmitted?.(input2.workflowId);
+  };
   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 () => {
@@ -24336,6 +24556,9 @@ async function waitForPlayCompletionByStream(input2) {
         }
         throw error;
       }
+      if (refreshed.runId === input2.workflowId && statusProvesPlayRunExecution(refreshed.status)) {
+        await confirmAdmission();
+      }
       return TERMINAL_PLAY_STATUSES2.has(refreshed.status) ? withDashboardUrl(refreshed) : null;
     })();
     durableStatusProbe = probe;
@@ -24347,6 +24570,9 @@ async function waitForPlayCompletionByStream(input2) {
   };
   const handleLiveEvent = async (event, probeDurableStatus) => {
     assertPlayWaitNotTimedOut({ ...input2, lastPhase });
+    if (getRunIdFromLiveEvent(event) === input2.workflowId && (eventConfirmsPlayRunLaunch(event) || eventProvesPlayRunExecution(event))) {
+      await confirmAdmission();
+    }
     const now = Date.now();
     if (now >= nextDurableProbeAt) {
       nextDurableProbeAt = now + durableStatusProbeIntervalMs;
@@ -24596,6 +24822,11 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
   let eventCount = 0;
   let firstRunIdMs = null;
   let launchConfirmed = false;
+  const confirmAdmission = async (runId) => {
+    if (launchConfirmed || !runId || runId === "pending") return;
+    launchConfirmed = true;
+    await input2.onRunAdmitted?.(runId);
+  };
   let lastPhase = null;
   const timeout = input2.waitTimeoutMs === null ? null : setTimeout(
     () => {
@@ -24619,6 +24850,9 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
       }
       throw error;
     }
+    if (refreshed.runId === lastKnownWorkflowId && statusProvesPlayRunExecution(refreshed.status)) {
+      await confirmAdmission(lastKnownWorkflowId);
+    }
     return TERMINAL_PLAY_STATUSES2.has(refreshed.status) ? {
       ...refreshed,
       dashboardUrl,
@@ -24646,8 +24880,8 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
           await input2.onRunStarted?.(eventRunId);
         }
       }
-      if (eventConfirmsPlayRunLaunch(event) && eventRunId === lastKnownWorkflowId) {
-        launchConfirmed = true;
+      if (!launchConfirmed && eventConfirmsPlayRunLaunch(event) && eventRunId === lastKnownWorkflowId) {
+        await confirmAdmission(lastKnownWorkflowId);
       }
       const workflowId = lastKnownWorkflowId || "pending";
       if (workflowId !== "pending" && !emittedDashboardUrl) {
@@ -24762,6 +24996,9 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
           firstRunIdMs,
           lastPhase
         });
+        if (statusProvesPlayRunExecution(canonicalTerminal.status)) {
+          await confirmAdmission(lastKnownWorkflowId);
+        }
         return canonicalTerminal;
       }
       if (lastKnownWorkflowId && launchConfirmed) {
@@ -24789,7 +25026,8 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
           waitTimeoutMs: input2.waitTimeoutMs,
           startedAt,
           state,
-          progress: input2.progress
+          progress: input2.progress,
+          onRunAdmitted: confirmAdmission
         });
       }
     }
@@ -24849,7 +25087,8 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
         waitTimeoutMs: input2.waitTimeoutMs,
         startedAt,
         state,
-        progress: input2.progress
+        progress: input2.progress,
+        onRunAdmitted: confirmAdmission
       });
     }
     if (!lastKnownWorkflowId && isTransientPlayStreamError(error)) {
@@ -24902,7 +25141,8 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
       waitTimeoutMs: input2.waitTimeoutMs,
       startedAt,
       state,
-      progress: input2.progress
+      progress: input2.progress,
+      onRunAdmitted: confirmAdmission
     });
   }
   const phaseSuffix = lastPhase && lastPhase.trim() ? ` (last observed phase: ${lastPhase.trim()})` : "";
@@ -25845,8 +26085,15 @@ function formatPackageDatasetActionLines(packaged, options) {
     const isReturned = datasetId && returned.datasetIds.has(datasetId) || returned.paths.has(path);
     const category = isReturned ? "returned" : dataset.recovered === true ? "recovered" : "persisted";
     const rowCount = typeof dataset.rowCount === "number" && Number.isFinite(dataset.rowCount) ? Math.max(0, Math.trunc(dataset.rowCount)) : null;
+    const lifecycle = readRecord(dataset.lifecycle);
+    const countUnconfirmed = lifecycle?.complete === false;
+    const persistedLowerBound = typeof lifecycle?.persistedRowsAtLeast === "number" && Number.isFinite(lifecycle.persistedRowsAtLeast) ? Math.max(0, Math.trunc(lifecycle.persistedRowsAtLeast)) : 0;
     const actions = readRecord(dataset.actions) ?? {};
-    if (includeSummary) {
+    if (countUnconfirmed) {
+      lines.push(
+        `  dataset ${path}: row count unconfirmed (at least ${formatInteger(persistedLowerBound)} persisted); export this run to inspect saved rows`
+      );
+    } else if (includeSummary) {
       if (category === "recovered" && Object.keys(actions).length === 0) {
         lines.push(
           `  dataset ${path}: available, ${rowCount === null ? "persisted" : formatInteger(rowCount)} rows persisted; re-running reuses completed work`
@@ -28194,7 +28441,8 @@ async function handleFileBackedRun(options, hooks) {
         waitTimeoutMs: options.waitTimeoutMs,
         open: options.open,
         progress,
-        onRunStarted: hooks?.onRunStarted
+        onRunStarted: hooks?.onRunStarted,
+        onRunAdmitted: hooks?.onRunAdmitted
       }).catch(async (error) => {
         throw await normalizePlayStartError(client2, error, playName);
       })
@@ -28235,6 +28483,7 @@ async function handleFileBackedRun(options, hooks) {
     })
   );
   await hooks?.onRunStarted?.(started.workflowId);
+  await hooks?.onRunAdmitted?.(started.workflowId);
   const resolvedDashboardUrl = buildPlayDashboardUrl(client2.baseUrl, playName);
   openPlayDashboard(resolvedDashboardUrl, options.open);
   progress.phase("started run");
@@ -28377,7 +28626,8 @@ async function handleNamedRun(options, hooks) {
         waitTimeoutMs: options.waitTimeoutMs,
         open: options.open,
         progress,
-        onRunStarted: hooks?.onRunStarted
+        onRunStarted: hooks?.onRunStarted,
+        onRunAdmitted: hooks?.onRunAdmitted
       }).catch(async (error) => {
         throw await normalizePlayStartError(client2, error, playName, {
           suggestMissingPlay: true
@@ -28423,6 +28673,7 @@ async function handleNamedRun(options, hooks) {
     })
   );
   await hooks?.onRunStarted?.(started.workflowId);
+  await hooks?.onRunAdmitted?.(started.workflowId);
   const resolvedDashboardUrl = buildPlayDashboardUrl(client2.baseUrl, playName);
   openPlayDashboard(resolvedDashboardUrl, options.open);
   progress.phase("started run");
@@ -28460,6 +28711,19 @@ async function handlePlayRun(args, hooks) {
         );
       }
       await hooks?.onRunStarted?.(runId);
+    },
+    onRunAdmitted: async (runId) => {
+      try {
+        await writePlayRunIdFile(options.runIdFile, runId, {
+          launchConfirmed: true
+        });
+      } catch (error) {
+        throw new Error(
+          `Run ${runId} was admitted, but its confirmation could not be persisted to ${options.runIdFile}: ${error instanceof Error ? error.message : String(error)}. Inspect it with 'deepline runs get ${runId} --json'; do not submit a replacement run.`,
+          { cause: error }
+        );
+      }
+      await hooks?.onRunAdmitted?.(runId);
     }
   } : hooks;
   if (options.target.kind === "file") {
@@ -28532,6 +28796,36 @@ async function handleRunGet(args) {
   });
   return 0;
 }
+async function handleRunLifecycleStatus(args) {
+  const usage = "Usage: deepline runs status <run-id> [--json]";
+  let runId;
+  try {
+    runId = parseRunIdPositional(args, usage);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : usage);
+    return 1;
+  }
+  const status = await new DeeplineClient().runs.status(runId);
+  if (argsWantJson(args)) {
+    printCommandEnvelope(status, { json: true });
+    return 0;
+  }
+  if (!status.available) {
+    console.log(`Scalar lifecycle status is not available for run ${runId}.`);
+    return 0;
+  }
+  const formatCount = (count) => count.value === null ? "unknown" : `${count.value}${count.confirmed ? "" : " (unconfirmed)"}`;
+  console.log(`${status.lifecycle.status} \xB7 ${runId}`);
+  console.log(
+    `Map-step work (summed, not unique rows): completed ${formatCount(status.mapStepWork.completed)} / ${formatCount(status.mapStepWork.total)}, failed ${formatCount(status.mapStepWork.failed)}`
+  );
+  if (status.lifecycle.status === "waiting") {
+    console.log(
+      status.wait.confirmed && status.wait.kind ? `Waiting: ${status.wait.kind}` : "Waiting reason: unknown"
+    );
+  }
+  return 0;
+}
 async function handleRunsRerun(args) {
   const usage = "Usage: deepline runs rerun <run-id> [--idempotency-key <key>] [--json]";
   let runId;
@@ -29004,7 +29298,12 @@ async function handleRunStop(args) {
   }
   const client2 = new DeeplineClient();
   const result = await client2.runs.stop(runId, { reason });
-  if (result.cancelling === true) {
+  if (result.cancelling === true && result.hitlCancellationPending !== true) {
+    const lines2 = [
+      `Cancellation queued for ${result.runId || runId}; sandbox cleanup is pending`,
+      ...result.hitlCancelledCount > 0 ? [`cancelled HITL waits: ${result.hitlCancelledCount}`] : [],
+      `inspect: deepline runs get ${runId} --full --json`
+    ];
     printCommandEnvelope(
       {
         ...result,
@@ -29012,10 +29311,7 @@ async function handleRunStop(args) {
           sections: [
             {
               title: "run stop",
-              lines: [
-                `Cancellation queued for ${result.runId || runId}; sandbox cleanup is pending`,
-                `inspect: deepline runs get ${runId} --full --json`
-              ]
+              lines: lines2
             }
           ]
         }
@@ -30928,6 +31224,12 @@ Examples:
   deepline runs export play/my-play/run/20260501t000000-000 --out output.csv
 `
   );
+  runs.command("status <runId>").description("Read bounded lifecycle and confirmed work counts for a run.").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
+    process.exitCode = await handleRunLifecycleStatus([
+      runId,
+      ...options.json ? ["--json"] : []
+    ]);
+  });
   runs.command("get <runId>").description(
     "Get status, progress, result, errors, and recovery metadata for a play run."
   ).addHelpText(
@@ -50500,8 +50802,8 @@ function readPendingToolExecution(path) {
   }
   return saved.idempotencyKey;
 }
-async function completePendingToolExecution(path) {
-  if (!path || !(0, import_node_fs26.existsSync)(path)) return;
+async function completePendingToolExecution(path, idempotencyKey) {
+  if (!path || !idempotencyKey || !(0, import_node_fs26.existsSync)(path)) return;
   await new Promise((resolve22, reject) => {
     const onError = (error) => {
       process.stdout.off("error", onError);
@@ -50517,7 +50819,12 @@ async function completePendingToolExecution(path) {
       }
     });
   });
-  if ((0, import_node_fs26.existsSync)(path)) (0, import_node_fs26.unlinkSync)(path);
+  try {
+    if (readPendingToolExecution(path) !== idempotencyKey) return;
+    (0, import_node_fs26.unlinkSync)(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
 }
 function safeFileStem(value) {
   return value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "tool";
@@ -50865,7 +51172,7 @@ async function executeTool(args) {
   const executeExitCode = toolExecuteExitCode(baseEnvelope);
   if (!parsed.outPath && (parsed.outputFormat === "json" || parsed.outputFormat === "auto" && shouldEmitJson())) {
     printCommandEnvelope(baseEnvelope, { json: true });
-    await completePendingToolExecution(pendingRecoveryPath);
+    await completePendingToolExecution(pendingRecoveryPath, idempotencyKey);
     return executeExitCode;
   }
   if (parsed.outputFormat === "json_file") {
@@ -50883,7 +51190,7 @@ async function executeTool(args) {
       },
       { json: true }
     );
-    await completePendingToolExecution(pendingRecoveryPath);
+    await completePendingToolExecution(pendingRecoveryPath, idempotencyKey);
     return executeExitCode;
   }
   if (!listConversion) {
@@ -50912,11 +51219,11 @@ async function executeTool(args) {
         },
         { json: parsed.outputFormat === "csv_file" || shouldEmitJson() }
       );
-      await completePendingToolExecution(pendingRecoveryPath);
+      await completePendingToolExecution(pendingRecoveryPath, idempotencyKey);
       return executeExitCode;
     }
     printCommandEnvelope(baseEnvelope, { json: false });
-    await completePendingToolExecution(pendingRecoveryPath);
+    await completePendingToolExecution(pendingRecoveryPath, idempotencyKey);
     return executeExitCode;
   }
   const rowOutput = projectRowOutput(listConversion);
@@ -50939,7 +51246,7 @@ async function executeTool(args) {
   });
   if (parsed.outputFormat === "csv_file") {
     printCommandEnvelope(materializedEnvelope, { json: true });
-    await completePendingToolExecution(pendingRecoveryPath);
+    await completePendingToolExecution(pendingRecoveryPath, idempotencyKey);
     return executeExitCode;
   }
   if (parsed.outPath) {
@@ -50948,7 +51255,7 @@ async function executeTool(args) {
       text: `Wrote ${csv.rowCount} row(s) to ${csv.path}
 `
     });
-    await completePendingToolExecution(pendingRecoveryPath);
+    await completePendingToolExecution(pendingRecoveryPath, idempotencyKey);
     return executeExitCode;
   }
   if (parsed.noPreview) {
@@ -50963,11 +51270,11 @@ async function executeTool(args) {
       { json: shouldEmitJson(), text: `${csv.path}
 ` }
     );
-    await completePendingToolExecution(pendingRecoveryPath);
+    await completePendingToolExecution(pendingRecoveryPath, idempotencyKey);
     return executeExitCode;
   }
   printCommandEnvelope(materializedEnvelope, { json: false });
-  await completePendingToolExecution(pendingRecoveryPath);
+  await completePendingToolExecution(pendingRecoveryPath, idempotencyKey);
   return executeExitCode;
 }