deepline 0.3.71 → 0.3.72

package/dist/cli/index.mjs

@@ -1199,7 +1199,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.71",
+  version: "0.3.72",
   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
@@ -3539,6 +3539,133 @@ function decodePlayRunPublicStatus(value) {
   }
 }
 
+// ../play-runtime/log-provenance.ts
+var LOG_LEVELS = [
+  "debug",
+  "info",
+  "warn",
+  "error"
+];
+var LOG_LEVEL_RANK = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var LOG_PROVENANCE_CLASSES = [
+  "user",
+  "lifecycle",
+  "replay",
+  "infra",
+  "diagnostic",
+  "receipt"
+];
+var LOG_PROVENANCE_POLICY = {
+  user: { watch: true, ui: true, debug: true },
+  lifecycle: { watch: true, ui: true, debug: true },
+  replay: { watch: false, ui: false, debug: true },
+  infra: { watch: false, ui: false, debug: true },
+  diagnostic: { watch: true, ui: true, debug: true },
+  receipt: { watch: false, ui: false, debug: true }
+};
+function logProvenanceReaches(provenance, surface) {
+  return LOG_PROVENANCE_POLICY[provenance][surface];
+}
+var PROVENANCE_SENTINEL = "
";
+var PROVENANCE_PREFIX = `${PROVENANCE_SENTINEL}prov:`;
+function logLevelReaches(level, minimum) {
+  return LOG_LEVEL_RANK[level] >= LOG_LEVEL_RANK[minimum];
+}
+function parseLogLevel(value) {
+  const normalized = value.trim().toLowerCase();
+  return LOG_LEVELS.includes(normalized) ? normalized : null;
+}
+function readProvenanceTag(line) {
+  if (!line.startsWith(PROVENANCE_PREFIX)) {
+    return { provenance: null, line };
+  }
+  const end = line.indexOf(PROVENANCE_SENTINEL, PROVENANCE_PREFIX.length);
+  if (end === -1) {
+    return { provenance: null, line };
+  }
+  const candidate = line.slice(PROVENANCE_PREFIX.length, end);
+  const provenance = LOG_PROVENANCE_CLASSES.includes(candidate) ? candidate : null;
+  return { provenance, line: line.slice(end + 1) };
+}
+function stripProvenanceTag(line) {
+  return readProvenanceTag(line).line;
+}
+function classifyLegacyLogLine(line) {
+  const message = stripLeadingTimestamp(line);
+  if (/recovered (?:from checkpoint|response from checkpoint)/i.test(message)) {
+    return "replay";
+  }
+  if (/^\[perf\] runtime receipt\b/i.test(message)) {
+    return "receipt";
+  }
+  if (/^\[perf\] runtime (?:map|state)\b/i.test(message) || /\[worker\] picked up run\b/.test(message) || /\[worker\] heartbeat\b/.test(message) || /\[worker\] progress completedRows=\d+ totalRows=\d+ rowUpdates=\d+/.test(
+    message
+  ) || /\[worker\] step started\b/.test(message) || /\[worker\] Preparing run files\b/.test(message) || /\[worker\] Run files ready\b/.test(message) || /\[worker\] Runtime ready\b/.test(message) || /\[worker\] Sandbox (?:starting|create start|create done|workspace ready|upload start|runner uploaded)\b/.test(
+    message
+  ) || /^\[event\] play\.step\.progress\b/.test(message) || /^\[event\] play\.run\.snapshot\b/.test(message) || /^\[event\] play\.sheet\.summary\b/.test(message)) {
+    return "infra";
+  }
+  if (/^\[warn\]/i.test(message) || /^\[error\]/i.test(message) || /^\[runtime\.[a-z_]*(?:failure|error)\]/i.test(message)) {
+    return "diagnostic";
+  }
+  return "user";
+}
+function classifyLogLine(line) {
+  const tagged = readProvenanceTag(line);
+  const provenance = tagged.provenance ?? classifyLegacyLogLine(tagged.line);
+  if (tagged.provenance !== null) {
+    return {
+      provenance,
+      level: inferLogLevel(provenance, tagged.line),
+      line: tagged.line
+    };
+  }
+  return {
+    provenance,
+    level: inferLogLevel(provenance, tagged.line),
+    line: tagged.line
+  };
+}
+function inferLogLevel(provenance, line) {
+  const message = stripLeadingTimestamp(line);
+  if (/^\[info\]/i.test(message)) {
+    return "info";
+  }
+  if (/^\[debug\]/i.test(message)) {
+    return "debug";
+  }
+  if (/^\[console\.error\]/i.test(message) || /^\[error\]/i.test(message)) {
+    return "error";
+  }
+  if (/^\[console\.warn\]/i.test(message) || /^\[warn\]/i.test(message)) {
+    return "warn";
+  }
+  if (/^\[console\.debug\]/i.test(message)) {
+    return "debug";
+  }
+  if (provenance === "replay" || provenance === "infra" || provenance === "receipt") {
+    return "debug";
+  }
+  if (provenance === "diagnostic") {
+    return "warn";
+  }
+  return "info";
+}
+function stripLeadingTimestamp(line) {
+  const match = line.match(/^\[([^\]]+)\]\s*([\s\S]*)$/);
+  if (!match) {
+    return line;
+  }
+  const inner = match[1] ?? "";
+  const isTimestamp = !Number.isNaN(new Date(inner).getTime());
+  return isTimestamp ? match[2] ?? line : line;
+}
+
 // ../play-runtime/run-snapshot-stream.ts
 function normalizePlayRunLiveStatus(value) {
   return normalizePlayRunLifecycleStatus(value);
@@ -3611,7 +3738,9 @@ function buildSnapshotFromLedger(snapshot) {
     finishedAt: snapshot.finishedAt ?? null,
     durationMs: snapshot.durationMs ?? null,
     updatedAt: snapshot.updatedAt ?? snapshot.finishedAt ?? snapshot.startedAt ?? null,
-    logs: snapshot.logTail,
+    // This snapshot is public SDK/API transport. Keep the historical plain
+    // timestamp-prefixed text while provenance remains runtime metadata.
+    logs: snapshot.logTail.map(stripProvenanceTag),
     totalLogCount: snapshot.totalLogCount,
     ...snapshot.logsTruncated ? { logsTruncated: true } : {},
     activeArtifactTableNamespace: snapshot.activeArtifactTableNamespace ?? null,
@@ -15254,7 +15383,7 @@ var PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   "  fetch(key: string, url: string | URL, init?: RequestInit & { headers?: HeadersInit & { 'Idempotency-Key'?: string; 'X-Idempotency-Key'?: string }; auth?: SecretAuthInput }, options?: FetchOptions): Promise<PlayFetchResponse>;",
   "  secrets: { get(name: string): SecretPromise; bearer(secret: string | SecretPromise | SecretHandle): SecretAuth; header(header: string, secret: string | SecretPromise | SecretHandle): SecretAuth };",
   `  runPlay<TOutput = unknown>(key: string, playRef: ${cloudReferenceType("ctx.runPlay.playRef")}, input: ${cloudReferenceType("ctx.runPlay.input")}, options: PlayCallOptions): Promise<TOutput>;`,
-  "  log(message: string): void;",
+  "  log(message: string, options?: { level?: 'debug' | 'info' | 'warn' | 'error' }): void;",
   `  sleep(ms: ${cloudReferenceType("ctx.sleep.ms")}): Promise<void>;`,
   "}",
   "export type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = { id: string; description?: string; input: PlayInputContract<TInput>; run: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>; bindings?: PlayBindings<TInput>; billing?: PlayBindings<TInput>['billing']; runtime?: PlayBindings<TInput>['runtime']; compatibility?: PlayBindings<TInput>['compatibility'] };",
@@ -16811,77 +16940,6 @@ function isInternalGlueStepId(stepId) {
   return typeof stepId === "string" && stepId.startsWith(INTERNAL_GLUE_NODE_ID_PREFIX);
 }
 
-// ../play-runtime/log-provenance.ts
-var LOG_PROVENANCE_CLASSES = [
-  "user",
-  "lifecycle",
-  "replay",
-  "infra",
-  "diagnostic",
-  "receipt"
-];
-var LOG_PROVENANCE_POLICY = {
-  user: { watch: true, ui: true, debug: true },
-  lifecycle: { watch: true, ui: true, debug: true },
-  replay: { watch: false, ui: false, debug: true },
-  infra: { watch: false, ui: false, debug: true },
-  diagnostic: { watch: true, ui: true, debug: true },
-  receipt: { watch: false, ui: false, debug: true }
-};
-function logProvenanceReaches(provenance, surface) {
-  return LOG_PROVENANCE_POLICY[provenance][surface];
-}
-var PROVENANCE_SENTINEL = "
";
-var PROVENANCE_PREFIX = `${PROVENANCE_SENTINEL}prov:`;
-function readProvenanceTag(line) {
-  if (!line.startsWith(PROVENANCE_PREFIX)) {
-    return { provenance: null, line };
-  }
-  const end = line.indexOf(PROVENANCE_SENTINEL, PROVENANCE_PREFIX.length);
-  if (end === -1) {
-    return { provenance: null, line };
-  }
-  const candidate = line.slice(PROVENANCE_PREFIX.length, end);
-  const provenance = LOG_PROVENANCE_CLASSES.includes(candidate) ? candidate : null;
-  return { provenance, line: line.slice(end + 1) };
-}
-function classifyLegacyLogLine(line) {
-  const message = stripLeadingTimestamp(line);
-  if (/recovered (?:from checkpoint|response from checkpoint)/i.test(message)) {
-    return "replay";
-  }
-  if (/^\[perf\] runtime receipt\b/i.test(message)) {
-    return "receipt";
-  }
-  if (/^\[perf\] runtime (?:map|state)\b/i.test(message) || /\[worker\] picked up run\b/.test(message) || /\[worker\] heartbeat\b/.test(message) || /\[worker\] progress completedRows=\d+ totalRows=\d+ rowUpdates=\d+/.test(
-    message
-  ) || /\[worker\] step started\b/.test(message) || /\[worker\] Preparing run files\b/.test(message) || /\[worker\] Run files ready\b/.test(message) || /\[worker\] Runtime ready\b/.test(message) || /\[worker\] Sandbox (?:starting|create start|create done|workspace ready|upload start|runner uploaded)\b/.test(
-    message
-  ) || /^\[event\] play\.step\.progress\b/.test(message) || /^\[event\] play\.run\.snapshot\b/.test(message) || /^\[event\] play\.sheet\.summary\b/.test(message)) {
-    return "infra";
-  }
-  if (/^\[warn\]/i.test(message) || /^\[error\]/i.test(message) || /^\[runtime\.[a-z_]*(?:failure|error)\]/i.test(message)) {
-    return "diagnostic";
-  }
-  return "user";
-}
-function classifyLogLine(line) {
-  const tagged = readProvenanceTag(line);
-  if (tagged.provenance !== null) {
-    return { provenance: tagged.provenance, line: tagged.line };
-  }
-  return { provenance: classifyLegacyLogLine(tagged.line), line: tagged.line };
-}
-function stripLeadingTimestamp(line) {
-  const match = line.match(/^\[([^\]]+)\]\s*([\s\S]*)$/);
-  if (!match) {
-    return line;
-  }
-  const inner = match[1] ?? "";
-  const isTimestamp = !Number.isNaN(new Date(inner).getTime());
-  return isTimestamp ? match[2] ?? line : line;
-}
-
 // ../play-runtime/fixture-behavior.ts
 var FIXTURE_BEHAVIOR_VERSION = 1;
 var FIXTURE_BEHAVIOR_RESPONSE_VERSION = 2;
@@ -18309,7 +18367,11 @@ var TERMINAL_PLAY_STATUSES2 = /* @__PURE__ */ new Set([
 var PLAY_START_TRANSIENT_RETRY_DELAYS_MS = [500, 1500];
 var PLAY_PROGRESS_HEARTBEAT_INTERVAL_MS = 15e3;
 var PLAY_STATUS_HEARTBEAT_INTERVAL_MS = 15e3;
-function watchSurfaceReaches(state, provenance) {
+function watchSurfaceReaches(state, provenance, level) {
+  const minimumLevel = state.logLevel ?? (state.verbose ? "debug" : "info");
+  if (!logLevelReaches(level, minimumLevel)) {
+    return false;
+  }
   if (logProvenanceReaches(provenance, "watch")) {
     return true;
   }
@@ -18504,7 +18566,7 @@ function emitLiveDebugTableHints(input2) {
       process.stdout
     );
   }
-  if (!watchSurfaceReaches(input2.state, "infra")) {
+  if (!watchSurfaceReaches(input2.state, "infra", "debug")) {
     return;
   }
   const tableNamespace = extractTableNamespaceFromLiveEvent(input2.event);
@@ -18607,7 +18669,7 @@ function getStepTransitionLineFromLiveEvent(event, state) {
   if (isTerminal) {
     state.terminalStepIds.add(stepId);
   }
-  if (isReplayEcho && !watchSurfaceReaches(state, "replay")) {
+  if (isReplayEcho && !watchSurfaceReaches(state, "replay", "debug")) {
     return null;
   }
   return `step ${label}: ${status}`;
@@ -19011,6 +19073,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
     lastLogIndex: 0,
     emittedRunnerStarted: false,
     verbose: input2.verboseLogs === true,
+    logLevel: input2.logLevel ?? "info",
     lastProgressSignature: null,
     lastProgressHeartbeatAt: 0,
     lastStatusHeartbeatAt: 0
@@ -19389,6 +19452,9 @@ function formatPlayLogLine(rawLine, status, state) {
   const message = timestampMatch?.[2] ?? line;
   const prefix = timestamp ? `${timestamp} ` : "";
   if (/\[worker\] picked up run\b/.test(message)) {
+    if (!logLevelReaches("info", state.logLevel ?? "info")) {
+      return null;
+    }
     if (state.emittedRunnerStarted) {
       return null;
     }
@@ -19405,6 +19471,9 @@ function formatPlayLogLine(rawLine, status, state) {
     /^Starting map over (\d+) items with (\d+) fields \(key: ([^;]+); (\d+) already satisfied; (\d+) pending\)$/
   );
   if (mapStart) {
+    if (!logLevelReaches("info", state.logLevel ?? "info")) {
+      return null;
+    }
     const [, rows, fields, namespace, cached, pending] = mapStart;
     return `${prefix}map ${sourceLabelForNamespace(namespace)}: ${formatInteger(Number(rows))} rows, ${fields} fields, ${formatInteger(Number(cached))} cached, ${formatInteger(Number(pending))} pending`;
   }
@@ -19412,10 +19481,13 @@ function formatPlayLogLine(rawLine, status, state) {
     /^Map completed: (\d+) results \((\d+) executed, (\d+) already satisfied\)$/
   );
   if (mapDone) {
+    if (!logLevelReaches("info", state.logLevel ?? "info")) {
+      return null;
+    }
     const [, results, executed, cached] = mapDone;
     return `${prefix}done: ${formatInteger(Number(results))} results, ${formatInteger(Number(executed))} executed, ${formatInteger(Number(cached))} cached`;
   }
-  if (!watchSurfaceReaches(state, classified.provenance)) {
+  if (!watchSurfaceReaches(state, classified.provenance, classified.level)) {
     return null;
   }
   return `${prefix}${message}`;
@@ -21151,13 +21223,12 @@ function parsePlayRunOptions(args) {
   const watch = !args.includes("--no-wait");
   let jsonOutput = watch ? args.includes("--json") : argsWantJson(args);
   const fullJson = args.includes("--full");
-  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 = explicitDebugLogs || debugMapLatency;
+  let logLevel = "info";
+  let hasExplicitLogLevel = false;
   let waitTimeoutMs = null;
   let maxConcurrentExternalCalls = null;
   let maxConcurrentRows = null;
@@ -21178,6 +21249,23 @@ function parsePlayRunOptions(args) {
       input2 = parseJsonInput(args[++index]);
       continue;
     }
+    if (arg === "--log-level" || arg.startsWith("--log-level=")) {
+      const value = arg === "--log-level" ? args[++index] : arg.slice("--log-level=".length);
+      if (!value || value.startsWith("--")) {
+        throw new Error(
+          "--log-level requires one of: debug, info, warn, error."
+        );
+      }
+      const parsed = parseLogLevel(value);
+      if (!parsed) {
+        throw new Error(
+          `Unsupported --log-level ${JSON.stringify(value)}. Use debug, info, warn, or error.`
+        );
+      }
+      logLevel = parsed;
+      hasExplicitLogLevel = true;
+      continue;
+    }
     if (arg === "--run-id-file") {
       const value = args[index + 1];
       if (!value || value.startsWith("--")) {
@@ -21356,6 +21444,17 @@ function parsePlayRunOptions(args) {
       "--live, --latest, and --revision-id only apply to named plays."
     );
   }
+  if (debugMapLatency && logLevel === "info") logLevel = "debug";
+  const usesDebugAlias = args.includes("--logs") || args.some((_, index) => isBarePlayRunDebugFlag(args, index));
+  if (usesDebugAlias && hasExplicitLogLevel && logLevel !== "debug") {
+    throw new Error(
+      "--debug/--logs conflicts with a non-debug --log-level. Use one level selector."
+    );
+  }
+  if (usesDebugAlias) logLevel = "debug";
+  const explicitDebugLogs = usesDebugAlias || logLevel === "debug";
+  const emitLogs = !jsonOutput || explicitDebugLogs || hasExplicitLogLevel;
+  const verboseLogs = explicitDebugLogs || debugMapLatency;
   return {
     target: filePath ? { kind: "file", path: filePath } : { kind: "name", name: playName },
     input: input2,
@@ -21364,6 +21463,7 @@ function parsePlayRunOptions(args) {
     watch,
     emitLogs,
     verboseLogs,
+    logLevel,
     jsonOutput,
     fullJson,
     waitTimeoutMs,
@@ -22261,6 +22361,7 @@ async function handleFileBackedRun(options, hooks) {
         jsonOutput: options.jsonOutput,
         emitLogs: options.emitLogs,
         verboseLogs: options.verboseLogs,
+        logLevel: options.logLevel,
         waitTimeoutMs: options.waitTimeoutMs,
         open: options.open,
         progress,
@@ -22443,6 +22544,7 @@ async function handleNamedRun(options, hooks) {
         jsonOutput: options.jsonOutput,
         emitLogs: options.emitLogs,
         verboseLogs: options.verboseLogs,
+        logLevel: options.logLevel,
         waitTimeoutMs: options.waitTimeoutMs,
         open: options.open,
         progress,
@@ -22560,12 +22662,13 @@ 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 === "--debug" || arg === "--compact" || arg === "--log-failed" || arg === "--failed" || arg === "--limit") {
-      if (arg === "--limit" && args[index + 1]) {
+    if (arg === "--json" || arg === "--full" || arg === "--input" || arg === "--logs" || arg === "--debug" || arg === "--compact" || arg === "--log-failed" || arg === "--failed" || arg === "--limit" || arg === "--log-level") {
+      if ((arg === "--limit" || arg === "--log-level") && args[index + 1]) {
         index += 1;
       }
       continue;
     }
+    if (arg.startsWith("--log-level=")) continue;
     if ((arg === "--out" || arg === "--reason" || arg === "--dataset") && args[index + 1]) {
       index += 1;
       continue;
@@ -22727,7 +22830,7 @@ async function handleRunsList(args) {
   return 0;
 }
 async function handleRunTail(args) {
-  const usage = "Usage: deepline runs tail <run-id> [--json | --jsonl] [--compact] [--debug]";
+  const usage = "Usage: deepline runs tail <run-id> [--json | --jsonl] [--compact] [--log-level debug|info|warn|error]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage);
@@ -22735,6 +22838,9 @@ async function handleRunTail(args) {
     console.error(error instanceof Error ? error.message : usage);
     return 1;
   }
+  let logLevel = "info";
+  let hasExplicitLogLevel = false;
+  let usesDebugAlias = false;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--cursor") {
@@ -22743,7 +22849,28 @@ async function handleRunTail(args) {
       );
       return 1;
     }
-    if (arg.startsWith("--") && arg !== "--json" && arg !== "--jsonl" && arg !== "--compact" && arg !== "--logs" && arg !== "--debug") {
+    if (arg === "--log-level" || arg.startsWith("--log-level=")) {
+      const value = arg === "--log-level" ? args[++index] : arg.slice("--log-level=".length);
+      if (!value || value.startsWith("--")) {
+        console.error("--log-level requires one of: debug, info, warn, error.");
+        return 1;
+      }
+      const parsed = parseLogLevel(value);
+      if (!parsed) {
+        console.error(
+          `Unsupported --log-level ${JSON.stringify(value)}. Use debug, info, warn, or error.`
+        );
+        return 1;
+      }
+      logLevel = parsed;
+      hasExplicitLogLevel = true;
+      continue;
+    }
+    if (arg === "--logs" || arg === "--debug") {
+      usesDebugAlias = true;
+      continue;
+    }
+    if (arg.startsWith("--") && arg !== "--json" && arg !== "--jsonl" && arg !== "--compact") {
       console.error(`${arg} is not supported by deepline runs tail.`);
       return 1;
     }
@@ -22752,10 +22879,17 @@ 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) {
+  if (usesDebugAlias && hasExplicitLogLevel && logLevel !== "debug") {
     console.error(
-      "--debug is redundant with --jsonl: JSON Lines already includes every canonical live event."
+      "--debug conflicts with a non-debug --log-level. Use one level selector."
+    );
+    return 1;
+  }
+  if (usesDebugAlias) logLevel = "debug";
+  const debug = logLevel === "debug";
+  if (args.includes("--jsonl") && (debug || hasExplicitLogLevel)) {
+    console.error(
+      "--log-level cannot be combined with --jsonl: JSON Lines already includes every canonical live event."
     );
     return 1;
   }
@@ -22769,7 +22903,8 @@ async function handleRunTail(args) {
     lastProgressSignature: null,
     lastProgressHeartbeatAt: 0,
     lastStatusHeartbeatAt: 0,
-    verbose: debug
+    verbose: debug,
+    logLevel
   };
   const status = await client2.runs.tail(runId, {
     onEvent: jsonLines ? (event) => {
@@ -22781,8 +22916,8 @@ async function handleRunTail(args) {
         })}
 `
       );
-    } : compact || debug ? (event) => {
-      if (debug) {
+    } : compact || debug || hasExplicitLogLevel ? (event) => {
+      if (debug || hasExplicitLogLevel) {
         for (const line of getLogLinesFromLiveEvent(event)) {
           const formatted = formatPlayLogLine(
             line,
@@ -22817,7 +22952,7 @@ async function handleRunTail(args) {
       }
     } : void 0,
     // Human mode only: in --json mode emit nothing non-protocol.
-    onReconnect: jsonOutput && !debug ? void 0 : ({ reason }) => {
+    onReconnect: jsonOutput && !debug && !hasExplicitLogLevel ? void 0 : ({ reason }) => {
       process.stderr.write(
         `[runs tail] stream ended without a terminal status; reconnecting to run ${runId} (${reason})
 `
@@ -22833,7 +22968,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] [--debug]";
+  const usage = "Usage: deepline runs logs <run-id> [--limit 200] [--failed] [--out run.log] [--log-level debug|info|warn|error] [--json]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage);
@@ -22843,10 +22978,34 @@ async function handleRunLogs(args) {
   }
   let limit = 200;
   let outPath = null;
+  let logLevel = "debug";
+  let hasExplicitLogLevel = false;
+  let usesDebugAlias = false;
   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") {
+    if (arg === "--debug" || arg === "--logs") {
+      usesDebugAlias = true;
+      continue;
+    }
+    if (arg === "--json" || arg === "--failed") {
+      continue;
+    }
+    if (arg === "--log-level" || arg.startsWith("--log-level=")) {
+      const value = arg === "--log-level" ? args[++index] : arg.slice("--log-level=".length);
+      if (!value || value.startsWith("--")) {
+        console.error("--log-level requires one of: debug, info, warn, error.");
+        return 1;
+      }
+      const parsed = parseLogLevel(value);
+      if (!parsed) {
+        console.error(
+          `Unsupported --log-level ${JSON.stringify(value)}. Use debug, info, warn, or error.`
+        );
+        return 1;
+      }
+      logLevel = parsed;
+      hasExplicitLogLevel = true;
       continue;
     }
     if (arg === "--limit" && args[index + 1]) {
@@ -22862,6 +23021,13 @@ async function handleRunLogs(args) {
       return 1;
     }
   }
+  if (usesDebugAlias && hasExplicitLogLevel && logLevel !== "debug") {
+    console.error(
+      "--debug conflicts with a non-debug --log-level. Use one level selector."
+    );
+    return 1;
+  }
+  if (usesDebugAlias) logLevel = "debug";
   if (failed && outPath) {
     console.error(
       "--failed cannot be combined with --out. Remove --failed to export the full persisted log stream."
@@ -22871,7 +23037,7 @@ async function handleRunLogs(args) {
   const client2 = new DeeplineClient();
   if (outPath) {
     const result2 = await client2.runs.logs(runId, { all: true });
-    const logs = result2.entries;
+    const logs = result2.entries.filter((line) => logLevelReaches(classifyLogLine(line).level, logLevel)).map((line) => classifyLogLine(line).line);
     writeFileSync10(outPath, `${logs.join("\n")}${logs.length > 0 ? "\n" : ""}`);
     printCommandEnvelope(
       {
@@ -22879,6 +23045,7 @@ async function handleRunLogs(args) {
         log_path: outPath,
         lineCount: logs.length,
         totalCount: result2.totalCount,
+        logLevel,
         ...result2.logsTruncated ? { logsTruncated: true } : {},
         local: { log_path: outPath },
         render: {
@@ -22899,27 +23066,47 @@ async function handleRunLogs(args) {
     );
     return 0;
   }
-  const result = await client2.runs.logs(runId, { limit, failed });
-  const text = buildRunLogsText(result);
+  const result = await client2.runs.logs(runId, {
+    ...failed ? { limit, failed: true } : { all: logLevel !== "debug", limit }
+  });
+  const matchingEntries = result.entries.filter(
+    (line) => logLevelReaches(classifyLogLine(line).level, logLevel)
+  );
+  const entries = failed ? matchingEntries : matchingEntries.slice(-limit);
+  const matchingEntriesTruncated = !failed && matchingEntries.length > limit;
+  const filteredResult = {
+    ...result,
+    entries,
+    returnedCount: entries.length,
+    truncated: result.truncated || matchingEntriesTruncated,
+    hasMore: result.hasMore || matchingEntriesTruncated,
+    view: failed ? result.view : "tail",
+    next: {
+      ...result.next ?? {},
+      logs: `deepline runs logs ${result.runId} --out run.log --log-level ${logLevel} --json`
+    }
+  };
+  const text = buildRunLogsText(filteredResult);
   printCommandEnvelope(
     {
       runId: result.runId,
       totalCount: result.totalCount,
-      returnedCount: result.returnedCount,
+      returnedCount: entries.length,
       firstSequence: result.firstSequence,
       lastSequence: result.lastSequence,
-      truncated: result.truncated,
-      hasMore: result.hasMore,
+      truncated: filteredResult.truncated,
+      hasMore: filteredResult.hasMore,
+      logLevel,
       ...result.logsTruncated ? { logsTruncated: true } : {},
-      entries: result.entries,
-      ...result.view ? { view: result.view } : {},
+      entries,
+      ...filteredResult.view ? { view: filteredResult.view } : {},
       ...result.association ? { association: result.association } : {},
       ...result.warning ? { warning: result.warning } : {},
       next: {
         ...result.next ?? {},
-        export: `deepline runs logs ${result.runId} --out run.log --json`
+        export: `deepline runs logs ${result.runId} --out run.log --log-level ${logLevel} --json`
       },
-      render: { sections: [{ title: "run logs", lines: result.entries }] }
+      render: { sections: [{ title: "run logs", lines: entries }] }
     },
     {
       json: argsWantJson(args),
@@ -22929,7 +23116,7 @@ async function handleRunLogs(args) {
   return 0;
 }
 function buildRunLogsText(result) {
-  const lines = [...result.entries];
+  const lines = result.entries.map((line) => classifyLogLine(line).line);
   if (result.warning) {
     if (lines.length > 0) lines.push("");
     lines.push(`warning: ${result.warning}`);
@@ -24313,6 +24500,7 @@ Examples:
   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 --input '{"domain":"stripe.com"}' --log-level debug
   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
@@ -24332,9 +24520,12 @@ 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", "Compatibility alias for --debug").option(
+  ).option("--logs", "Compatibility alias for --log-level debug").option(
     "--debug [value]",
-    "Stream complete customer-safe runtime logs when passed without a value; otherwise pass input.debug"
+    "Compatibility alias for --log-level debug when bare; --debug <value> remains legacy Play input.debug"
+  ).option(
+    "--log-level <level>",
+    "Minimum live log severity: debug, info (default), warn, or error"
   ).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"
@@ -24384,6 +24575,7 @@ Pass-through input flags:
       ...options.watch || options.wait ? ["--watch"] : [],
       ...options.logs ? ["--logs"] : [],
       ...options.debug === true ? ["--debug"] : typeof options.debug === "string" ? ["--debug", options.debug] : [],
+      ...options.logLevel ? ["--log-level", options.logLevel] : [],
       ...options.tailTimeoutMs ? ["--tail-timeout-ms", options.tailTimeoutMs] : [],
       ...options.force ? ["--force"] : [],
       ...options.forceToolRefresh ? ["--force-tool-refresh"] : [],
@@ -24692,10 +24884,15 @@ Concepts:
   tail reads the live stream. logs fetches persisted logs after the fact.
   stop mutates cloud state by requesting cancellation.
 
+Debug a run:
+  Active:    deepline runs tail <run-id> --log-level debug
+  Historical: deepline runs logs <run-id> --out run.log --log-level debug --json
+  Full state: deepline runs get <run-id> --full --json
+
 Examples:
   deepline runs get play/my-play/run/20260501t000000-000 --json
   deepline runs tail play/my-play/run/20260501t000000-000
-  deepline runs logs play/my-play/run/20260501t000000-000 --out run.log --json
+  deepline runs logs play/my-play/run/20260501t000000-000 --out run.log --log-level debug --json
   deepline runs list --play my-play --status failed --json
   deepline runs list --status running --json
   deepline runs stop play/my-play/run/20260501t000000-000 --reason "stale lock" --json
@@ -24801,13 +24998,15 @@ 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. Use --debug
-  (or legacy --logs) to also print customer-safe runtime log lines to stderr.
+  ends with the same compact package shape as runs get --json. --log-level
+  filters the rendered customer-safe runtime log lines; debug includes runtime
+  and receipt diagnostics and writes them to stderr alongside JSON output.
 
 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 --log-level debug
+  deepline runs tail play/my-play/run/20260501t000000-000 --log-level error
   deepline runs tail play/my-play/run/20260501t000000-000 --jsonl
 `
   ).option("--json", "Emit one terminal JSON package after the run completes").option(
@@ -24816,9 +25015,9 @@ 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"
+  ).option("--logs", "Compatibility alias for --log-level debug").option("--debug", "Compatibility alias for --log-level debug").option(
+    "--log-level <level>",
+    "Minimum severity: debug, info (default), warn, or error"
   ).action(async (runId, options) => {
     process.exitCode = await handleRunTail([
       runId,
@@ -24826,7 +25025,8 @@ Examples:
       ...options.jsonl ? ["--jsonl"] : [],
       ...options.compact ? ["--compact"] : [],
       ...options.logs ? ["--logs"] : [],
-      ...options.debug ? ["--debug"] : []
+      ...options.debug ? ["--debug"] : [],
+      ...options.logLevel ? ["--log-level", options.logLevel] : []
     ]);
   });
   runs.command("logs <runId>").description("Fetch persisted logs for a play run.").addHelpText(
@@ -24834,29 +25034,30 @@ Examples:
     `
 Notes:
   Prints a bounded recent log preview by default. Use --out to write the full
-  persisted log stream to a local file. --debug (or legacy --logs) is accepted
-  for script parity; this command already returns the unfiltered durable stream.
+  retained stream to a local file. Use --log-level to filter by severity;
+  default debug preserves the complete historical 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
+  deepline runs logs play/my-play/run/20260501t000000-000 --log-level error
+  deepline runs logs play/my-play/run/20260501t000000-000 --out run.log --log-level debug --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("--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) => {
+  ).option("--out <path>", "Write the full retained log stream to a file").option("--failed", "Show the bounded terminal-failure log window").option(
+    "--log-level <level>",
+    "Minimum severity: debug (default), info, warn, or error"
+  ).option("--logs", "Compatibility alias for --log-level debug").option("--debug", "Compatibility alias for --log-level debug").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.logLevel ? ["--log-level", options.logLevel] : [],
       ...options.logs ? ["--logs"] : [],
       ...options.debug ? ["--debug"] : [],
       ...options.json ? ["--json"] : []