deepline 0.3.64 → 0.3.66

package/dist/bundling-sources/shared_libs/play-runtime/test-async-batching.ts

@@ -0,0 +1,141 @@
+import {
+  defineBatchStrategyMap,
+  type BatchOperationStrategy,
+} from './batching-types';
+
+type TestAsyncLookupPayload = Record<string, unknown> & {
+  key: string;
+  row_number: number;
+  capacity_key: string;
+  polls_before_terminal?: number;
+  result_page_size?: number;
+  pre_attach_delay_ms?: number;
+};
+
+type TestAsyncBatchPayload = Record<string, unknown> & {
+  key: string;
+  capacity_key: string;
+  wait_for_completion: true;
+  terminal_outcome: 'completed';
+  polls_before_terminal?: number;
+  result_page_size?: number;
+  pre_attach_delay_ms?: number;
+  items: Array<{
+    itemKey: string;
+    payload: { key: string; row_number: number };
+  }>;
+};
+
+type TestAsyncBatchResult = Record<string, unknown> & {
+  items?: Array<{
+    itemKey?: string;
+    result?: Record<string, unknown>;
+  }>;
+};
+
+function resultItems(
+  value: unknown,
+): NonNullable<TestAsyncBatchResult['items']> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return [];
+  const record = value as Record<string, unknown>;
+  if (Array.isArray(record.items)) {
+    return record.items as NonNullable<TestAsyncBatchResult['items']>;
+  }
+  for (const candidate of [record.data, record.result, record.output]) {
+    const nested = resultItems(candidate);
+    if (nested.length > 0) return nested;
+  }
+  return [];
+}
+
+export const testAsyncContractLookupBatchStrategy: BatchOperationStrategy<
+  TestAsyncLookupPayload,
+  TestAsyncBatchPayload,
+  TestAsyncBatchResult,
+  Record<string, unknown>
+> = {
+  sourceOperation: 'test_async_contract_lookup',
+  batchOperation: 'test_async_contract_start',
+  kind: 'async_dataset_job',
+  maxBatchSize: 3,
+  bucketKeyPayloadFields: [
+    'capacity_key',
+    'polls_before_terminal',
+    'result_page_size',
+    'pre_attach_delay_ms',
+  ],
+  canBatchWith(left, right) {
+    return (
+      left.capacity_key === right.capacity_key &&
+      left.polls_before_terminal === right.polls_before_terminal &&
+      left.result_page_size === right.result_page_size &&
+      left.pre_attach_delay_ms === right.pre_attach_delay_ms
+    );
+  },
+  toBucketKey(payload) {
+    return JSON.stringify([
+      payload.capacity_key,
+      payload.polls_before_terminal ?? null,
+      payload.result_page_size ?? null,
+      payload.pre_attach_delay_ms ?? null,
+    ]);
+  },
+  toItemKey(payload) {
+    return payload.key;
+  },
+  compile(payloads) {
+    const first = payloads[0]!;
+    const items = payloads.map((payload) => ({
+      itemKey: payload.key,
+      payload: { key: payload.key, row_number: payload.row_number },
+    }));
+    return {
+      batchOperation: 'test_async_contract_start',
+      batchPayload: {
+        key: `async-contract:${first.capacity_key}:${items.map((item) => item.itemKey).join(',')}`,
+        capacity_key: first.capacity_key,
+        wait_for_completion: true,
+        terminal_outcome: 'completed',
+        ...(first.polls_before_terminal !== undefined
+          ? { polls_before_terminal: first.polls_before_terminal }
+          : {}),
+        ...(first.result_page_size !== undefined
+          ? { result_page_size: first.result_page_size }
+          : {}),
+        ...(first.pre_attach_delay_ms !== undefined
+          ? { pre_attach_delay_ms: first.pre_attach_delay_ms }
+          : {}),
+        items,
+      },
+      items: payloads.map((payload) => ({
+        itemKey: payload.key,
+        payload,
+      })),
+    };
+  },
+  splitResult(fullResult, compiled) {
+    const items = resultItems(fullResult);
+    if (items.length !== compiled.items.length) {
+      throw new Error(
+        `Synthetic async batch returned ${items.length} results for ${compiled.items.length} inputs.`,
+      );
+    }
+    return compiled.items.map((item, index) => {
+      const resultItem = items[index];
+      if (!resultItem || resultItem.itemKey !== item.itemKey) {
+        throw new Error(
+          `Synthetic async batch result ${index} did not preserve item identity ${item.itemKey}.`,
+        );
+      }
+      return {
+        itemKey: item.itemKey,
+        result: resultItem.result ?? {},
+        rawResult: resultItem,
+      };
+    });
+  },
+};
+
+export const testAsyncBatchStrategies = defineBatchStrategyMap({
+  test_async_contract_lookup: testAsyncContractLookupBatchStrategy,
+});

package/dist/bundling-sources/shared_libs/play-runtime/tool-execute-retry-policy.ts

@@ -16,10 +16,17 @@ export const TOOL_EXECUTE_IDEMPOTENCY_IN_PROGRESS_MAX_ATTEMPTS =
   TOOL_EXECUTE_IDEMPOTENCY_IN_PROGRESS_RETRY_DELAYS_MS.length + 1;
 export const TOOL_EXECUTE_RATE_LIMIT_MAX_ATTEMPTS = 8;
 export const TOOL_EXECUTE_BARE_RATE_LIMIT_MAX_ATTEMPTS = 2;
+// A Deepline async-capacity denial means the provider has not been called.
+// Treat it as queueing, not a failed physical provider attempt. The enclosing
+// tool deadline remains the hard bound; this prevents a normal one-minute
+// queue wait from being compressed into eight five-second retries.
+export const TOOL_EXECUTE_CONCURRENCY_BACKPRESSURE_MAX_ATTEMPTS = 65;
 export const TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS = 3;
 export const TOOL_EXECUTE_TRANSPORT_RETRY_DELAY_MS = 1_000;
 export const TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS = 1_000;
 export const TOOL_EXECUTE_RETRY_DELAY_MAX_MS = 5_000;
+export const TOOL_EXECUTE_RATE_LIMIT_RETRY_DELAY_MAX_MS = 30_000;
+export const TOOL_EXECUTE_CONCURRENCY_BACKPRESSURE_DELAY_MAX_MS = 5 * 60_000;
 export const TOOL_EXECUTE_BARE_RATE_LIMIT_BACKPRESSURE_MS = 60_000;
 export const TOOL_EXECUTE_AUTH_SCOPE_CHANGED_CODE = 'AUTH_SCOPE_CHANGED';
 export const TOOL_EXECUTE_CUSTOMER_DB_STORAGE_UNAVAILABLE_CODE =
@@ -50,6 +57,7 @@ export type ToolExecuteHttpRetryDecision = {
   attemptCap: number;
   reason:
     | 'rate_limit'
+    | 'concurrency_backpressure'
     | 'idempotency_in_progress'
     | 'gateway_invocation_in_progress'
     | 'customer_db_storage_unavailable'
@@ -131,6 +139,19 @@ function isCustomerDbStorageUnavailableResponse(input: {
   );
 }
 
+function isConcurrencyBackpressureResponse(input: {
+  status: number;
+  bodyText: string;
+}): boolean {
+  if (input.status !== 429) return false;
+  const body = parseJsonObject(input.bodyText);
+  return (
+    body?.code === 'RATE_LIMIT' &&
+    body.rate_limit_kind === 'concurrency' &&
+    body.failure_origin === 'deepline_rate_limit'
+  );
+}
+
 function idempotencyInProgressRetryDelayMs(attempt: number): number {
   return (
     TOOL_EXECUTE_IDEMPOTENCY_IN_PROGRESS_RETRY_DELAYS_MS[
@@ -164,6 +185,7 @@ function decideToolExecuteHttpRetry(input: {
   idempotencyInProgress?: boolean;
   gatewayInvocationInProgress?: boolean;
   customerDbStorageUnavailable?: boolean;
+  concurrencyBackpressure?: boolean;
   hardBillingFailure?: boolean;
   hasRetryAfterHeader?: boolean;
   transientHttpRetrySafe?: boolean;
@@ -177,6 +199,13 @@ function decideToolExecuteHttpRetry(input: {
     };
   }
   if (input.status === 429) {
+    if (input.concurrencyBackpressure) {
+      return {
+        retryable: true,
+        attemptCap: TOOL_EXECUTE_CONCURRENCY_BACKPRESSURE_MAX_ATTEMPTS,
+        reason: 'concurrency_backpressure',
+      };
+    }
     if (!input.hasRetryAfterHeader) {
       return {
         retryable: true,
@@ -241,6 +270,7 @@ export function createToolExecuteHttpFailureAttemptTracker(): ToolExecuteHttpFai
     number
   > = {
     rate_limit: 0,
+    concurrency_backpressure: 0,
     idempotency_in_progress: 0,
     gateway_invocation_in_progress: 0,
     customer_db_storage_unavailable: 0,
@@ -267,6 +297,10 @@ export function createToolExecuteHttpFailureAttemptTracker(): ToolExecuteHttpFai
           status: input.status,
           bodyText: input.bodyText ?? '',
         }),
+        concurrencyBackpressure: isConcurrencyBackpressureResponse({
+          status: input.status,
+          bodyText: input.bodyText ?? '',
+        }),
         hasRetryAfterHeader: true,
         transientHttpRetrySafe: input.transientHttpRetrySafe === true,
       });
@@ -312,11 +346,13 @@ export function classifyToolExecuteHttpFailure(input: {
     isGatewayInvocationInProgressResponse(input);
   const customerDbStorageUnavailable =
     isCustomerDbStorageUnavailableResponse(input);
+  const concurrencyBackpressure = isConcurrencyBackpressureResponse(input);
   const initialRetryDecision = decideToolExecuteHttpRetry({
     status: input.status,
     idempotencyInProgress,
     gatewayInvocationInProgress,
     customerDbStorageUnavailable,
+    concurrencyBackpressure,
     hasRetryAfterHeader,
     transientHttpRetrySafe,
   });
@@ -348,6 +384,7 @@ export function classifyToolExecuteHttpFailure(input: {
     idempotencyInProgress,
     gatewayInvocationInProgress,
     customerDbStorageUnavailable,
+    concurrencyBackpressure,
     hardBillingFailure,
     hasRetryAfterHeader,
     transientHttpRetrySafe,
@@ -366,23 +403,31 @@ export function classifyToolExecuteHttpFailure(input: {
     error.receiptFailureKind = 'repairable';
   }
   const retryDelayMs =
-    input.status === 429
+    retryDecision.reason === 'concurrency_backpressure'
       ? Math.min(
-          TOOL_EXECUTE_RETRY_DELAY_MAX_MS,
+          TOOL_EXECUTE_CONCURRENCY_BACKPRESSURE_DELAY_MAX_MS,
           Math.max(
             retryAfterMs,
             TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS * input.attempt,
           ),
         )
-      : retryDecision.reason === 'idempotency_in_progress' &&
-          !hasRetryAfterHeader
-        ? idempotencyInProgressRetryDelayMs(input.attempt)
-        : retryDecision.reason === 'gateway_invocation_in_progress' &&
+      : input.status === 429
+        ? Math.min(
+            TOOL_EXECUTE_RATE_LIMIT_RETRY_DELAY_MAX_MS,
+            Math.max(
+              retryAfterMs,
+              TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS * input.attempt,
+            ),
+          )
+        : retryDecision.reason === 'idempotency_in_progress' &&
             !hasRetryAfterHeader
           ? idempotencyInProgressRetryDelayMs(input.attempt)
-          : retryAfterMs > 0
-            ? Math.min(TOOL_EXECUTE_RETRY_DELAY_MAX_MS, retryAfterMs)
-            : TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS;
+          : retryDecision.reason === 'gateway_invocation_in_progress' &&
+              !hasRetryAfterHeader
+            ? idempotencyInProgressRetryDelayMs(input.attempt)
+            : retryAfterMs > 0
+              ? Math.min(TOOL_EXECUTE_RETRY_DELAY_MAX_MS, retryAfterMs)
+              : TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS;
   return {
     ...retryDecision,
     error,
@@ -401,6 +446,8 @@ export function classifyToolExecuteHttpFailure(input: {
           : TOOL_EXECUTE_BARE_RATE_LIMIT_BACKPRESSURE_MS
         : null,
     chargeRetryBudget:
-      shouldRetry && retryDecision.reason !== 'gateway_invocation_in_progress',
+      shouldRetry &&
+      retryDecision.reason !== 'gateway_invocation_in_progress' &&
+      retryDecision.reason !== 'concurrency_backpressure',
   };
 }

package/dist/cli/index.js

@@ -1214,7 +1214,7 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.64",
+  version: "0.3.66",
   updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
   packageCapabilities: {
     updatePreferences: 1
@@ -16758,9 +16758,7 @@ function readProvenanceTag(line) {
     return { provenance: null, line };
   }
   const candidate = line.slice(PROVENANCE_PREFIX.length, end);
-  const provenance = LOG_PROVENANCE_CLASSES.includes(
-    candidate
-  ) ? candidate : null;
+  const provenance = LOG_PROVENANCE_CLASSES.includes(candidate) ? candidate : null;
   return { provenance, line: line.slice(end + 1) };
 }
 function classifyLegacyLogLine(line) {
@@ -17094,12 +17092,16 @@ var PLAY_RUN_RESERVED_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--watch",
   "--no-wait",
   "--logs",
+  "--debug",
   "--full",
   "--force",
   "--force-tool-refresh",
   "--open",
   "--debug-map-latency"
 ]);
+function isBarePlayRunDebugFlag(args, index) {
+  return args[index] === "--debug" && (args[index + 1] === void 0 || args[index + 1].startsWith("--"));
+}
 async function pathExistsIncludingSymlink(path) {
   try {
     await (0, import_promises6.lstat)(path);
@@ -21057,12 +21059,13 @@ function parsePlayRunOptions(args) {
   const watch = !args.includes("--no-wait");
   let jsonOutput = watch ? args.includes("--json") : argsWantJson(args);
   const fullJson = args.includes("--full");
-  const emitLogs = !jsonOutput || args.includes("--logs");
+  const explicitDebugLogs = args.includes("--logs") || args.some((_, index) => isBarePlayRunDebugFlag(args, index));
+  const emitLogs = !jsonOutput || explicitDebugLogs;
   const force = args.includes("--force");
   const forceToolRefresh = args.includes("--force-tool-refresh");
   const open2 = args.includes("--open");
   const debugMapLatency = args.includes("--debug-map-latency");
-  const verboseLogs = args.includes("--logs") || debugMapLatency;
+  const verboseLogs = explicitDebugLogs || debugMapLatency;
   let waitTimeoutMs = null;
   let maxConcurrentExternalCalls = null;
   let maxConcurrentRows = null;
@@ -21193,6 +21196,20 @@ function parsePlayRunOptions(args) {
       waitTimeoutMs = parsePositiveInteger3(args[++index], arg);
       continue;
     }
+    if (arg === "--debug" && args[index + 1] && !args[index + 1].startsWith("--")) {
+      input2 ??= {};
+      setDottedInputValue(input2, "debug", parseInputFlagValue(args[++index]));
+      continue;
+    }
+    if (arg.startsWith("--debug=")) {
+      input2 ??= {};
+      setDottedInputValue(
+        input2,
+        "debug",
+        parseInputFlagValue(arg.slice("--debug=".length))
+      );
+      continue;
+    }
     if (PLAY_RUN_RESERVED_BOOLEAN_FLAGS.has(arg)) {
       if (arg === "--watch") {
         continue;
@@ -22451,7 +22468,7 @@ async function handlePlayRun(args, hooks) {
 function parseRunIdPositional(args, usage) {
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
-    if (arg === "--json" || arg === "--full" || arg === "--input" || arg === "--logs" || arg === "--compact" || arg === "--log-failed" || arg === "--failed" || arg === "--limit") {
+    if (arg === "--json" || arg === "--full" || arg === "--input" || arg === "--logs" || arg === "--debug" || arg === "--compact" || arg === "--log-failed" || arg === "--failed" || arg === "--limit") {
       if (arg === "--limit" && args[index + 1]) {
         index += 1;
       }
@@ -22599,7 +22616,7 @@ async function handleRunsList(args) {
   return 0;
 }
 async function handleRunTail(args) {
-  const usage = "Usage: deepline runs tail <run-id> [--json | --jsonl] [--compact]";
+  const usage = "Usage: deepline runs tail <run-id> [--json | --jsonl] [--compact] [--debug]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage);
@@ -22615,7 +22632,7 @@ async function handleRunTail(args) {
       );
       return 1;
     }
-    if (arg.startsWith("--") && arg !== "--json" && arg !== "--jsonl" && arg !== "--compact") {
+    if (arg.startsWith("--") && arg !== "--json" && arg !== "--jsonl" && arg !== "--compact" && arg !== "--logs" && arg !== "--debug") {
       console.error(`${arg} is not supported by deepline runs tail.`);
       return 1;
     }
@@ -22624,6 +22641,13 @@ async function handleRunTail(args) {
     console.error("--json and --jsonl cannot be used together.");
     return 1;
   }
+  const debug = args.includes("--logs") || args.includes("--debug");
+  if (args.includes("--jsonl") && debug) {
+    console.error(
+      "--debug is redundant with --jsonl: JSON Lines already includes every canonical live event."
+    );
+    return 1;
+  }
   const client2 = new DeeplineClient();
   const jsonLines = args.includes("--jsonl");
   const jsonOutput = !jsonLines && argsWantJson(args);
@@ -22633,7 +22657,8 @@ async function handleRunTail(args) {
     emittedRunnerStarted: false,
     lastProgressSignature: null,
     lastProgressHeartbeatAt: 0,
-    lastStatusHeartbeatAt: 0
+    lastStatusHeartbeatAt: 0,
+    verbose: debug
   };
   const status = await client2.runs.tail(runId, {
     onEvent: jsonLines ? (event) => {
@@ -22645,7 +22670,20 @@ async function handleRunTail(args) {
         })}
 `
       );
-    } : compact && !jsonOutput ? (event) => {
+    } : compact || debug ? (event) => {
+      if (debug) {
+        for (const line of getLogLinesFromLiveEvent(event)) {
+          const formatted = formatPlayLogLine(
+            line,
+            void 0,
+            compactState
+          );
+          if (formatted) process.stderr.write(`${formatted}
+`);
+          compactState.lastLogIndex += 1;
+        }
+      }
+      if (!compact || jsonOutput) return;
       const transition = getStepTransitionLineFromLiveEvent(
         event,
         compactState
@@ -22668,7 +22706,7 @@ async function handleRunTail(args) {
       }
     } : void 0,
     // Human mode only: in --json mode emit nothing non-protocol.
-    onReconnect: jsonOutput ? void 0 : ({ reason }) => {
+    onReconnect: jsonOutput && !debug ? void 0 : ({ reason }) => {
       process.stderr.write(
         `[runs tail] stream ended without a terminal status; reconnecting to run ${runId} (${reason})
 `
@@ -22684,7 +22722,7 @@ async function handleRunTail(args) {
   return status.status === "failed" ? 1 : 0;
 }
 async function handleRunLogs(args) {
-  const usage = "Usage: deepline runs logs <run-id> [--limit 200] [--failed] [--out run.log] [--json]";
+  const usage = "Usage: deepline runs logs <run-id> [--limit 200] [--failed] [--out run.log] [--json] [--debug]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage);
@@ -22697,12 +22735,20 @@ async function handleRunLogs(args) {
   const failed = args.includes("--failed");
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
+    if (arg === "--debug" || arg === "--logs" || arg === "--json" || arg === "--failed") {
+      continue;
+    }
     if (arg === "--limit" && args[index + 1]) {
       limit = parsePositiveInteger3(args[++index], "--limit");
       continue;
     }
     if (arg === "--out" && args[index + 1]) {
       outPath = (0, import_node_path14.resolve)(args[++index]);
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      console.error(`${arg} is not supported by deepline runs logs.`);
+      return 1;
     }
   }
   if (failed && outPath) {
@@ -24175,9 +24221,9 @@ Examples:
   ).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("--logs", "Compatibility alias for --debug").option(
+    "--debug [value]",
+    "Stream complete customer-safe runtime logs when passed without a value; otherwise pass input.debug"
   ).option("--tail-timeout-ms <ms>", "Timeout while watching the run stream").option("--force", "Start a fresh run graph").option(
     "--force-tool-refresh",
     "Refresh completed tool receipts; may repeat billed provider calls"
@@ -24226,6 +24272,7 @@ Pass-through input flags:
       ...options.runIdFile ? ["--run-id-file", options.runIdFile] : [],
       ...options.watch || options.wait ? ["--watch"] : [],
       ...options.logs ? ["--logs"] : [],
+      ...options.debug === true ? ["--debug"] : typeof options.debug === "string" ? ["--debug", options.debug] : [],
       ...options.tailTimeoutMs ? ["--tail-timeout-ms", options.tailTimeoutMs] : [],
       ...options.force ? ["--force"] : [],
       ...options.forceToolRefresh ? ["--force-tool-refresh"] : [],
@@ -24643,11 +24690,13 @@ Notes:
   logs for persisted log history. In human output, --compact prints deduplicated
   step transitions and progress instead of the full event stream. --json emits
   one terminal package. --jsonl emits canonical live events as JSON Lines and
-  ends with the same compact package shape as runs get --json.
+  ends with the same compact package shape as runs get --json. Use --debug
+  (or legacy --logs) to also print customer-safe runtime log lines to stderr.
 
 Examples:
   deepline runs tail play/my-play/run/20260501t000000-000
   deepline runs tail play/my-play/run/20260501t000000-000 --compact
+  deepline runs tail play/my-play/run/20260501t000000-000 --debug
   deepline runs tail play/my-play/run/20260501t000000-000 --jsonl
 `
   ).option("--json", "Emit one terminal JSON package after the run completes").option(
@@ -24656,12 +24705,17 @@ Examples:
   ).option(
     "--compact",
     "Show deduplicated human step transitions and progress"
+  ).option("--logs", "Compatibility alias for --debug").option(
+    "--debug",
+    "Print customer-safe runtime log lines to stderr while tailing"
   ).action(async (runId, options) => {
     process.exitCode = await handleRunTail([
       runId,
       ...options.json ? ["--json"] : [],
       ...options.jsonl ? ["--jsonl"] : [],
-      ...options.compact ? ["--compact"] : []
+      ...options.compact ? ["--compact"] : [],
+      ...options.logs ? ["--logs"] : [],
+      ...options.debug ? ["--debug"] : []
     ]);
   });
   runs.command("logs <runId>").description("Fetch persisted logs for a play run.").addHelpText(
@@ -24669,24 +24723,31 @@ Examples:
     `
 Notes:
   Prints a bounded recent log preview by default. Use --out to write the full
-  persisted log stream to a local file.
+  persisted log stream to a local file. --debug (or legacy --logs) is accepted
+  for script parity; this command already returns the unfiltered durable stream.
 
 Examples:
   deepline runs logs play/my-play/run/20260501t000000-000
   deepline runs logs play/my-play/run/20260501t000000-000 --limit 500
   deepline runs logs play/my-play/run/20260501t000000-000 --failed --json
+  deepline runs logs play/my-play/run/20260501t000000-000 --debug
   deepline runs logs play/my-play/run/20260501t000000-000 --out run.log --json
 `
   ).option(
     "--limit <count>",
     "Maximum recent log lines to print without --out",
     "200"
-  ).option("--out <path>", "Write the full persisted log stream to a file").option("--failed", "Show the bounded terminal-failure log window").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
+  ).option("--out <path>", "Write the full persisted log stream to a file").option("--failed", "Show the bounded terminal-failure log window").option("--logs", "Compatibility alias for --debug").option(
+    "--debug",
+    "Explicitly request the same persisted log view (no provenance filtering)"
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunLogs([
       runId,
       ...options.limit ? ["--limit", options.limit] : [],
       ...options.out ? ["--out", options.out] : [],
       ...options.failed ? ["--failed"] : [],
+      ...options.logs ? ["--logs"] : [],
+      ...options.debug ? ["--debug"] : [],
       ...options.json ? ["--json"] : []
     ]);
   });