deepline 0.3.272 → 0.3.274

package/dist/cli/index.mjs

@@ -1953,7 +1953,7 @@ configureProxyFromEnv();
 import { mkdtemp as mkdtemp4, rm as rm4, writeFile as writeFile7 } from "fs/promises";
 import { join as join29 } from "path";
 import { tmpdir as tmpdir7 } from "os";
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 
 // ../plays/trigger-config-route.ts
 function playTriggerConfigPath(playName) {
@@ -3507,7 +3507,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.272",
+  version: "0.3.274",
   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
@@ -7290,7 +7290,7 @@ var DeeplineClient = class _DeeplineClient {
   }
   playRunCommand(play) {
     const target = play.reference || play.name;
-    return `deepline plays run ${target}${playInputExampleArgs(play.inputSchema)} --watch`;
+    return `deepline plays run ${target}${playInputExampleArgs(play.inputSchema)}`;
   }
   starterPlayPath(play) {
     const target = play.reference || play.name;
@@ -7851,7 +7851,7 @@ var DeeplineClient = class _DeeplineClient {
    * Convenience wrapper around {@link registerPlayArtifact} plus
    * {@link startPlayRun}. This is the canonical file-backed path used by wrappers.
    * The returned id can be passed to {@link getPlayStatus} to retrieve the same
-   * durable `{ result }` object that the CLI prints after `--watch` completes.
+   * durable `{ result }` object that the CLI prints after `plays run` completes.
    *
    * @param code - Source string fallback; the bundled artifact should be passed in `options.artifact`
    * @param csvPath - Path to input CSV file, or `null`
@@ -7972,7 +7972,7 @@ var DeeplineClient = class _DeeplineClient {
    * Get the current status of a play execution.
    *
    * Internal/advanced primitive. Public callers should usually prefer
-   * {@link runPlay}, {@link PlayJob.get}, or `deepline plays run --watch`.
+   * {@link runPlay}, {@link PlayJob.get}, or `deepline plays run`.
    *
    * @param workflowId - Play-run id from {@link startPlayRun}
    * @returns Current status with progress logs and partial results
@@ -8363,7 +8363,7 @@ var DeeplineClient = class _DeeplineClient {
     );
     return { ...response, runs: response.runs ?? [] };
   }
-  /** Read batches rather than silently truncating a long key list. */
+  /** Read retained tool results without executing tools, preserving supplied key order and batching 100 keys per request. Obtain keys from exported evidence or execution metadata; each key must be nonempty, at most 2,048 characters and contain no CR, LF or NUL. Missing/expired results have an explicit per-key error. */
   async getRunReceipts(runId, options) {
     if (!options.keys.length || options.keys.some(
       (key) => typeof key !== "string" || !key.trim() || key.length > 2048 || /[\r\n\0]/.test(key)
@@ -8419,7 +8419,7 @@ var DeeplineClient = class _DeeplineClient {
     );
   }
   /**
-   * Fetch persisted logs for a run using the public runs resource model.
+   * Read a run's retained text tail (default 200), full retained stream (`all`), or terminal failure window (`failed`, at most 20). These are existing reads; sampling and retention loss cannot be recovered. See [run logs and events](run-events.md) for structured search and payload retrieval.
    *
    * This is the SDK equivalent of:
    *
@@ -8498,7 +8498,7 @@ var DeeplineClient = class _DeeplineClient {
       ...probe.logsTruncated ? { logsTruncated: true } : {}
     };
   }
-  /** Search bounded, structured runtime history without requiring a run id. */
+  /** Read structured history across the active organization without requiring a run ID. Defaults to the last hour, newest first; use the returned cursor and exact time bounds to continue. See [run logs and events](run-events.md) for all kinds, indexed fields, payloads and SDK/API response types. */
   async searchRunEvents(options = {}) {
     const now = Date.now();
     const params = new URLSearchParams({
@@ -14911,7 +14911,7 @@ import {
 } from "fs/promises";
 import { homedir as homedir6, tmpdir as tmpdir5 } from "os";
 import { basename as basename4, dirname as dirname11, extname as extname3, join as join15, resolve as resolve14 } from "path";
-import { Option as Option3 } from "commander";
+import { Option as Option4 } from "commander";
 
 // ../plays/settings-contract.ts
 import { z } from "zod";
@@ -15689,6 +15689,244 @@ function registerPlayTriggerConfigCommands(plays) {
 // src/cli/commands/play.ts
 import { createHash as createHash4, randomUUID as randomUUID4 } from "crypto";
 
+// src/cli/run-logs-help.ts
+var EVENT_DETAILS = {
+  "run.created": {
+    emittedBy: "Run admission",
+    payloadFields: ["status", "playName", "runtimeBackend"]
+  },
+  "run.started": {
+    emittedBy: "Execution coordinator",
+    payloadFields: ["playName", "runtimeBackend"]
+  },
+  "run.waiting": {
+    emittedBy: "Durable wait handling",
+    payloadFields: ["waitKind", "waitUntil"]
+  },
+  "run.resumed": { emittedBy: "Durable wait handling", payloadFields: [] },
+  "run.completed": {
+    emittedBy: "Run finalization",
+    payloadFields: ["result", "resultSummary", "terminalWorkCounterSegment"]
+  },
+  "run.failed": {
+    emittedBy: "Run finalization",
+    payloadFields: [
+      "error",
+      "result",
+      "resultSummary",
+      "terminalWorkCounterSegment"
+    ]
+  },
+  "run.cancelled": {
+    emittedBy: "Run cancellation",
+    payloadFields: ["error", "result"]
+  },
+  "step.started": {
+    emittedBy: "Managed step execution",
+    payloadFields: ["stepId", "label", "kind", "artifactTableNamespace"]
+  },
+  "step.progress": {
+    emittedBy: "Managed step execution",
+    payloadFields: ["stepId", "label", "kind", "status", "progress"]
+  },
+  "step.completed": {
+    emittedBy: "Managed step execution",
+    payloadFields: ["stepId", "label", "kind", "artifactTableNamespace"]
+  },
+  "step.failed": {
+    emittedBy: "Managed step execution",
+    payloadFields: [
+      "stepId",
+      "label",
+      "kind",
+      "error",
+      "artifactTableNamespace"
+    ]
+  },
+  "step.skipped": {
+    emittedBy: "Managed step execution",
+    payloadFields: ["stepId", "label", "kind", "artifactTableNamespace"]
+  },
+  "log.appended": {
+    emittedBy: "ctx.log and runtime/coordinator messages",
+    payloadFields: [
+      "lines",
+      "lineContexts",
+      "producerAttempt",
+      "channelOffset",
+      "logsTruncated"
+    ]
+  },
+  "dataset.lifecycle": {
+    emittedBy: "Managed dataset storage",
+    payloadFields: [
+      "datasetId",
+      "path",
+      "tableNamespace",
+      "phase",
+      "persistedRows",
+      "succeededRows",
+      "failedRows",
+      "complete",
+      "bornFrom"
+    ]
+  },
+  "activity.observed": {
+    emittedBy: "Managed provider/dataset/runner activity",
+    payloadFields: ["observation"]
+  },
+  "work.counters": {
+    emittedBy: "Runtime work accounting",
+    payloadFields: [
+      "attempt",
+      "invocationSeq",
+      "segmentId",
+      "logicalCalls",
+      "providerRequests",
+      "provider429s",
+      "final"
+    ]
+  }
+};
+var RUN_LOGS_KIND_HELP = [
+  ...Object.entries(RUN_EVENT_KIND_CATALOG).map(([kind, descriptor]) => ({
+    kind,
+    description: descriptor.description,
+    ...EVENT_DETAILS[kind]
+  })),
+  ...Object.entries(RUN_RECEIPT_SEARCH_KIND_CATALOG).map(
+    ([kind, descriptor]) => ({
+      kind,
+      description: descriptor.description,
+      emittedBy: "Durable work receipt settlement",
+      payloadFields: ["status", "output", "error", "errorPayload"]
+    })
+  ),
+  {
+    kind: RUN_EVENT_SEARCH_FALLBACK_KIND,
+    description: "Fallback for an observation without a recognized event type.",
+    emittedBy: "Event indexing",
+    payloadFields: []
+  }
+];
+var SECTIONS = [
+  {
+    title: "Choose the read",
+    paragraphs: [
+      "These commands read existing evidence; they do not start a run or execute a provider. Replace <run-id>, <play-name> and other angle-bracket values with identifiers returned by the CLI.",
+      "Text logs: runs logs <run-id> returns the last 200 retained lines by default. --out writes the full retained stream to a local file. --log-level filters text severity; debug includes all retained levels. --failed reads only a terminal-failed run\u2019s last 20 retained lines and reports retention limitations.",
+      "Event search: omit the run ID, or add any of --since, --until, --play, --kind, --where, --payloads, --cursor, --runtime-namespace or --runtime-backend. A supplied run ID then narrows the search. --limit and --json alone do not switch a run\u2019s text logs to event search. Text-only flags --out, --failed and --log-level cannot be combined with event search.",
+      "Current status and returned output selectors: runs get <run-id> --json. Live observation: runs watch <run-id>. Dataset rows: runs export <run-id> --dataset <returned-selector> --out rows.csv. A referenced tool response: runs receipt <run-id> --key <returned-receipt-key> --json. Read each command\u2019s --help for its options."
+    ],
+    commands: [
+      "deepline runs logs <run-id> --json",
+      "deepline runs logs <run-id> --out run.log --json",
+      "deepline runs logs --kind run.failed --json",
+      "deepline runs logs --kind step.failed --payloads --json",
+      "deepline runs logs --kind receipt.failed --payloads --json"
+    ]
+  },
+  {
+    title: "Search window and pagination",
+    paragraphs: [
+      "Search defaults to the last hour, newest first. Use explicit ISO UTC --since and --until values for reproducible queries; the maximum lookback is seven days. Default page size is 100 events; --limit accepts 1\u2013200. With --payloads, default and maximum are 10 events, with 16 MiB total payload data.",
+      "JSON returns events[], returnedCount, since, until, nextCursor and next.logs. Run the returned next.logs command to continue with the same filters and UTC window; nextCursor is opaque. A bounded page or an empty result does not establish whole-run coverage or application health."
+    ],
+    commands: [
+      "deepline runs logs <run-id> --kind log.appended --json",
+      "deepline runs logs --play <play-name> --since <UTC-start> --until <UTC-end> --json"
+    ]
+  },
+  {
+    title: "Fields you can filter with --where",
+    paragraphs: [
+      "Identity strings: orgId, runId, playName, runtimeScope. These come from authenticated execution state; filters only narrow your authorized organization/runtime. Preview reads require the existing runtime credential and an authorized --runtime-namespace; --runtime-backend selects daytona or modal.",
+      "Event string: kind. Optional strings: source, stepId, stepKind, status, datasetId, phase, provider, operation. Optional positive integer: producerAttempt. These fields exist only when recorded; inspect a returned event before filtering on an optional field.",
+      'stepId/stepKind describe recorded step work; datasetId/phase describe dataset lifecycle (registered, available, failed). provider/operation appear on typed provider activity.observed events, not every receipt or provider call. status is the recorded status or activity state when present: run.completed and step.completed do not imply status == "completed". Select lifecycle outcomes with --kind.',
+      "context.<key> matches an authored flat scalar log field: string, number or boolean. Context cannot override event identity. Missing fields do not match. --where supports only $.field == literal predicates joined with &&, at most eight predicates and 512 bytes. No OR, ranges, wildcards, nested payload paths or text search. Time uses --since/--until; level and message are not --where fields.",
+      'Wrap the entire predicate in single shell quotes so $ and && reach the CLI unchanged. Inside it, strings use double quotes; numbers and booleans are unquoted. Types must match: 2 differs from "2", false differs from "false". Examples use illustrative recorded values; use your own step IDs, dataset IDs, provider/operation names and authored context. The context examples assume ctx.log recorded companyId: "acme_123", attempt: 2 and cached: false.'
+    ],
+    commands: [
+      "# Failed retained work with its stored error/result",
+      `deepline runs logs --kind receipt.failed --where '$.status == "failed"' --payloads --json`,
+      "# Failure details for one named step",
+      `deepline runs logs --kind step.failed --where '$.stepId == "company-lookup"' --payloads --json`,
+      "# Typed provider observations matching both fields",
+      `deepline runs logs --kind activity.observed --where '$.provider == "apollo" && $.operation == "company_lookup"' --json`,
+      "# Failed lifecycle transitions for one dataset",
+      `deepline runs logs --kind dataset.lifecycle --where '$.datasetId == "companies" && $.phase == "failed"' --payloads --json`,
+      "# Authored string context on log lines",
+      `deepline runs logs --kind log.appended --where '$.context.companyId == "acme_123"' --json`,
+      "# Authored number and boolean context, both required to match",
+      "deepline runs logs --kind log.appended --where '$.context.attempt == 2 && $.context.cached == false' --json",
+      "# Known producer identity within one run",
+      `deepline runs logs <run-id> --where '$.source == "worker" && $.producerAttempt == 1' --json`
+    ]
+  },
+  {
+    title: "What you get back",
+    paragraphs: [
+      "Search events include eventId, occurredAt, ingestedAt, kind, runId, playName, level and message. The CLI puts indexed fields directly on each events[] entry; SDK/API responses keep them under searchDoc. Log search message is a preview (up to 2,048 characters); use text logs or --out for full retained lines.",
+      "--payloads adds eventPayload for stored canonical events: lifecycle, step details/errors, activity observations, dataset transitions and work counters. Receipt matches instead hydrate payload with status, output, error and errorPayload. An event without a receipt does not promise a tool response; retained payloads may be unavailable. Neither --where nor event search indexes request/response bodies.",
+      "Search does not expose a receipt key or storage reference. To retrieve a specific retained tool response with runs receipt, use the receipt key returned in the run\u2019s exported evidence or tool execution metadata. For full row data, follow runs get output/export actions; dataset.lifecycle contains metadata, not all dataset rows.",
+      "The catalog lists known searchable kinds, including receipt outcomes and the runtime.event fallback. Use the exact dotted name with --kind. Future stored kinds can also be queried; this list is not a CLI validation allowlist. Events are observations, not a count of billed provider calls.",
+      "Catalog payload fields are possible producer fields, not required fields or --where paths. Canonical eventPayload uses type for the dotted event kind; its kind field, when present on a step, becomes indexed stepKind. Indexed log entries describe individual lines rather than reproducing the original lines batch.",
+      "Canonical event envelopes carry runId, type, occurredAt (producer milliseconds), source, optional seq and optional producer-owned payload. Search occurredAt/ingestedAt are UTC timestamp strings. source identifies the recorded producer; producerAttempt is present only when known.",
+      "activity.observed stores observation with activityId, stepId, target, state and observedAt. Targets describe provider, dataset, lease, runner, step or capacity work. State kinds are active, queued, waiting, retrying, scheduled, completed or failed; retry/wait detail stays in the payload. work.counters contains aggregate logicalCalls, providerRequests and provider429s, not per-call responses."
+    ],
+    commands: []
+  }
+];
+var RETENTION = [
+  "Event/log/receipt search shares the PlanetScale index. New runs marked runEventStore=planet_scale retain accepted event/log history in PlanetScale; Convex keeps current run/control state and eligible saved-Play rollup facts. Older unmarked runs retain their existing readers. No backfill is implied.",
+  "Search retention is seven days; receipt payload retention is independent. Logs reflect accepted, retained lines: runtime sampling and truncation can omit original console output. Read returned retention/sampling warnings; an export contains the full retained stream, not suppressed lines."
+];
+function wrapParagraph(text, indent2 = 2) {
+  const lines = [];
+  const padding = " ".repeat(indent2);
+  let line = padding;
+  for (const word of text.split(" ")) {
+    if (line.length + word.length > 80 && line.trim()) {
+      lines.push(line.trimEnd());
+      line = padding;
+    }
+    line += `${word} `;
+  }
+  lines.push(line.trimEnd());
+  return lines.join("\n");
+}
+function renderRunLogsHelp() {
+  const section = ({
+    title,
+    paragraphs,
+    commands
+  }) => [
+    `${title}:`,
+    ...paragraphs.flatMap((paragraph) => [wrapParagraph(paragraph), ""]),
+    ...commands.length ? ["  Common commands:", ...commands.map((command) => `    ${command}`)] : [],
+    ""
+  ];
+  return [
+    "",
+    ...section(SECTIONS[0]),
+    "Known --kind values (complete catalog):",
+    ...RUN_LOGS_KIND_HELP.flatMap(
+      ({ kind, description, emittedBy, payloadFields }) => [
+        `  ${kind}`,
+        wrapParagraph(description, 4),
+        wrapParagraph(
+          `Recorded by: ${emittedBy}. Payload fields: ${kind === RUN_EVENT_SEARCH_FALLBACK_KIND ? "producer-specific fields; inspect the returned payload" : payloadFields.join(", ") || "event envelope only"}.`,
+          4
+        )
+      ]
+    ),
+    "",
+    ...SECTIONS.slice(1).flatMap(section),
+    "Storage and retention:",
+    ...RETENTION.flatMap((paragraph) => [wrapParagraph(paragraph), ""])
+  ].join("\n");
+}
+
 // ../play-runtime/run-execution-state.ts
 function assertNeverState(value, what) {
   throw new Error(`Unhandled ${what}: ${JSON.stringify(value)}`);
@@ -16514,6 +16752,7 @@ import {
   relative as relative5,
   resolve as resolve13
 } from "path";
+import { Option as Option3 } from "commander";
 
 // src/cli/commands/plays/bootstrap.ts
 import {
@@ -16874,7 +17113,7 @@ Example: deepline plays bootstrap people-email --from csv:data/leads.csv --using
       `Unknown plays bootstrap template: ${rawTemplate}
 Supported templates: ${formatPlayBootstrapTemplates()}|${MONITOR_BOOTSTRAP_TEMPLATE}` + (looksLikePlayReference ? `
 
-"${rawTemplate}" looks like an existing play reference or file, not a bootstrap template. Do not run plays bootstrap on prebuilt/<play-name>. Use "deepline plays run ${rawTemplate} --input '{...}' --watch" to run it directly, "deepline plays describe ${rawTemplate} --json" to inspect its contract, or "deepline plays get ${rawTemplate} --source --out scratchpad.play.ts" to clone/edit it.` : "")
+"${rawTemplate}" looks like an existing play reference or file, not a bootstrap template. Do not run plays bootstrap on prebuilt/<play-name>. Use "deepline plays run ${rawTemplate} --input '{...}'" to run it directly, "deepline plays describe ${rawTemplate} --json" to inspect its contract, or "deepline plays get ${rawTemplate} --source --out scratchpad.play.ts" to clone/edit it.` : "")
     );
   }
   return rawTemplate;
@@ -17643,7 +17882,7 @@ function playUsesMapBackedRuntime(play) {
 }
 function assertComposablePlayRoute(input2) {
   if (!input2.playRef || !playUsesMapBackedRuntime(input2.play)) return;
-  const runCommand2 = input2.play?.runCommand?.trim() || `deepline plays run ${input2.playRef} --input '{...}' --watch`;
+  const runCommand2 = input2.play?.runCommand?.trim() || `deepline plays run ${input2.playRef} --input '{...}'`;
   throw new PlayBootstrapValidationError(
     `Cannot use ${input2.stageLabel} play:${input2.playRef} in plays bootstrap composition: the selected play is dataset-backed/direct-run-only. Child plays that use ctx.dataset() own durable table state and must be run directly, exported, or validated as their own play instead of wrapped with ctx.runPlay. Run it directly first: ${runCommand2}`
   );
@@ -17685,14 +17924,14 @@ function generatePlaySourceRowsBlock(input2) {
     sourcePlay: input2.sourcePlay
   })) {
     const sourcePlay = input2.sourcePlay;
-    const runCommand2 = sourcePlay?.runCommand?.trim() || `deepline plays run ${input2.source.value} --input '{...}' --watch`;
+    const runCommand2 = sourcePlay?.runCommand?.trim() || `deepline plays run ${input2.source.value} --input '{...}'`;
     return `// Source play ${input2.source.value} is dataset-backed/direct-run-only, so this generated play is stage 2.
   // Stage 1:
   //   ${runCommand2}
   // Stage 2:
   //   deepline runs export <stage-1-run-id> --dataset 'result.rows' --out source-export.csv
   // Stage 3:
-  //   deepline plays run <this-file.play.ts> --input '{"sourceCsv":"source-export.csv","limit":${input2.sourcePlay ? "5" : "5"}}' --watch
+  //   deepline plays run <this-file.play.ts> --input '{"sourceCsv":"source-export.csv","limit":${input2.sourcePlay ? "5" : "5"}}'
   const sourceDataset = await ctx.csv<${input2.collectionType}>(input.sourceCsv ?? './source-export.csv');
   const ${input2.collection}: ${input2.collectionType}[] = await sourceDataset.peek(limit);`;
   }
@@ -18172,7 +18411,7 @@ Notes:
 Examples:
   deepline plays bootstrap people-email --from csv:data/leads.csv --using play:prebuilt/name-and-domain-to-email-waterfall --limit 5 --out email-flow.play.ts
   deepline plays check email-flow.play.ts
-  deepline plays run email-flow.play.ts --input '{"limit":5}' --watch
+  deepline plays run email-flow.play.ts --input '{"limit":5}'
 
   deepline plays bootstrap people-email --from provider:dropleads_search_people --using providers:hunter_email_finder,leadmagic_email_finder --limit 5 --out prospecting.play.ts
   deepline plays bootstrap company-people-email --from provider:crustdata_companydb_search --people play:prebuilt/company-to-contact --email play:prebuilt/name-and-domain-to-email-waterfall --limit 5 --out account-contacts.play.ts
@@ -28126,7 +28365,7 @@ function buildPlayReferenceNotFoundMessage(input2) {
       lines.push("", `  ${suggestion.reference}`);
       if (input2.command === "run") {
         lines.push(
-          `    deepline plays run ${suggestion.reference} --input '{...}' --watch`
+          `    deepline plays run ${suggestion.reference} --input '{...}'`
         );
       } else if (input2.command === "get") {
         lines.push(`    deepline plays get ${suggestion.reference} --json`);
@@ -31450,7 +31689,9 @@ function buildOrdinaryPlayRunCommand(options, resolvedRevisionId) {
   }
   if (options.open) parts.push("--open");
   if (options.fullJson) parts.push("--full");
-  if (options.jsonOutput && options.emitLogs) parts.push("--logs");
+  if (options.jsonOutput && options.emitLogs) {
+    parts.push("--log-level", "debug");
+  }
   if (options.jsonOutput) parts.push("--json");
   return parts.join(" ");
 }
@@ -32534,7 +32775,7 @@ function parsePlayRunOptions(args) {
       }
       if (arg === "--tail") {
         throw new Error(
-          "--tail is removed for `plays run`; use `--watch` to stream completion output."
+          "--tail is removed for `plays run`; run waits and streams completion output by default."
         );
       }
       continue;
@@ -35164,7 +35405,7 @@ async function handlePlayList(args) {
         `    cost estimate: ${formatPlayCostEstimate(play.costEstimate)}`
       );
     }
-    lines.push(`    run: deepline plays run ${reference} --watch`);
+    lines.push(`    run: deepline plays run ${reference}`);
   }
   if (page.hasMore) {
     lines.push("List truncated \u2014 more plays are available.");
@@ -35986,7 +36227,6 @@ Run and retrieve results:
   2. Start and follow a new run: deepline plays run workflow.play.ts --csv contacts.csv
      This example requires input.csv. Use the selected Play's actual input fields.
      Run waits and shows progress by default; --no-wait returns immediately.
-     --watch and --wait are redundant compatibility aliases for the default.
   3. Read its overview: deepline runs get <run-id> --json
   4. Export complete rows: deepline runs export <run-id> --dataset <returned-selector> --out results.csv
   If disconnected, attach to the SAME run with deepline runs tail <run-id>.
@@ -36075,8 +36315,7 @@ Notes:
   Named plays run the live saved revision.
   File args accept local paths; the CLI stages files before submit.
   By default, run waits for completion and prints logs, previews, stats, and
-  next commands. --watch and --wait are accepted compatibility aliases for the
-  default behavior. Use --no-wait only when you intentionally want
+   next commands. Use --no-wait only when you intentionally want
   a fire-and-forget run id.
   --run-id-file writes the durable run id to a versioned JSON file as soon as
   the server accepts the run. The destination must not already exist.
@@ -36146,12 +36385,29 @@ Examples:
   ).option(
     "--fixture-behavior <json>",
     "Internal/testing: fixture response behavior JSON object or @file path"
-  ).option("--watch", "Compatibility alias; run waits by default").option("--wait", "Compatibility alias; run waits by default").option("--no-wait", "Start the run and return immediately").option(
+  ).addOption(
+    new Option3(
+      "--watch",
+      "Compatibility alias; run waits by default"
+    ).hideHelp()
+  ).addOption(
+    new Option3(
+      "--wait",
+      "Compatibility alias; run waits by default"
+    ).hideHelp()
+  ).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 --log-level debug").option(
-    "--debug [value]",
-    "Compatibility alias for --log-level debug when bare; --debug <value> remains legacy Play input.debug"
+  ).addOption(
+    new Option3(
+      "--logs",
+      "Compatibility alias for --log-level debug"
+    ).hideHelp()
+  ).addOption(
+    new Option3(
+      "--debug [value]",
+      "Compatibility alias for --log-level debug when bare; --debug <value> remains legacy Play input.debug"
+    ).hideHelp()
   ).option(
     "--log-level <level>",
     "Minimum live log severity: debug, info (default), warn, or error"
@@ -36833,9 +37089,8 @@ Notes:
   logs for persisted log history. In human output, --compact prints
   deduplicated step transitions and progress. --json emits one terminal
   package. --jsonl emits canonical watched events as JSON Lines and ends with
-  the same compact package shape as runs get --json. The tail command remains
-  an alias. --log-level
-  filters the rendered customer-safe runtime log lines; debug includes runtime
+  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:
@@ -36851,7 +37106,17 @@ Examples:
   ).option(
     "--compact",
     "Show deduplicated human step transitions and progress"
-  ).option("--logs", "Compatibility alias for --log-level debug").option("--debug", "Compatibility alias for --log-level debug").option(
+  ).addOption(
+    new Option3(
+      "--logs",
+      "Compatibility alias for --log-level debug"
+    ).hideHelp()
+  ).addOption(
+    new Option3(
+      "--debug",
+      "Compatibility alias for --log-level debug"
+    ).hideHelp()
+  ).option(
     "--log-level <level>",
     "Minimum severity: debug, info (default), warn, or error"
   ).action(async (runId, options) => {
@@ -36867,51 +37132,31 @@ Examples:
   });
   runs.command("logs [runId]").description(
     "Fetch one run\u2019s logs or search recent runtime events across runs."
-  ).addHelpText(
-    "after",
-    `
-Notes:
-  Prints a bounded recent log preview by default. Use --out to write the full
-  retained stream to a local file. Use --log-level to filter by severity;
-  default debug preserves the complete historical stream.
-
-  Search flags read the org-scoped event index (last hour by default, at most
-  seven days). Org, run, Play, runtime scope and known attempt identity are
-  attached automatically. --where accepts equality joined with && for orgId,
-  runId, playName, runtimeScope, producerAttempt, kind, status, source, stepId,
-  stepKind, datasetId, phase, provider, operation, and scalar context.<key>.
-  Filters only narrow the authenticated org/runtime scope. Provider and
-  operation come from typed provider activity observations; this does not
-  index request/response bodies or promise one event per provider call. --payloads
-  includes full result data in this command, capped at ten events and 16 MiB.
-
-  Event, log, and receipt search share one PlanetScale index. For runs marked
-  runEventStore=planet_scale, PlanetScale owns full event/log history; Convex
-  keeps the live run snapshot, admission fence, and eligible saved-Play rollup
-  facts. Marked-run log bodies are not copied into Convex. Unmarked legacy runs
-  keep their existing Convex event history and Run Log Stream.
-  Known --kind values: ${RUN_EVENT_SEARCH_KIND_VALUES.join(", ")}.
-
-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 --log-level error
-  deepline runs logs play/my-play/run/20260501t000000-000 --out run.log --log-level debug --json
-  deepline runs logs --since 2026-09-29T00:00:00Z --kind step.failed --json
-  deepline runs logs --kind activity.observed --where '$.provider == "apollo" && $.operation == "company_lookup"' --json
-  deepline runs logs --play my-play --where '$.context.companyId == "acme_123"' --json
-  deepline runs logs --where '$.status == "failed"' --payloads --play my-play --json
-`
-  ).option("--limit <count>", "Maximum log lines or search events to print").option("--out <path>", "Write the full retained log stream to a file").option("--failed", "Show the bounded terminal-failure log window").option(
+  ).addHelpText("after", renderRunLogsHelp()).option(
+    "--limit <count>",
+    "Text tail: default 200; search: default 100, max 200 (10 with --payloads)"
+  ).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").option("--since <timestamp>", "Search events since this UTC timestamp").option("--until <timestamp>", "Search events before this UTC timestamp").option("--play <name>", "Filter events by Play name").option("--kind <kind>", "Filter events by kind").option(
+  ).addOption(
+    new Option3(
+      "--logs",
+      "Compatibility alias for --log-level debug"
+    ).hideHelp()
+  ).addOption(
+    new Option3(
+      "--debug",
+      "Compatibility alias for --log-level debug"
+    ).hideHelp()
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--since <timestamp>", "Search events since this UTC timestamp").option("--until <timestamp>", "Search events before this UTC timestamp").option("--play <name>", "Filter events by Play name").option(
+    "--kind <kind>",
+    "Search one exact event kind; complete catalog below"
+  ).option(
     "--where <jsonpath>",
-    'Bound JSONPath equality over event fields (for example $.provider == "apollo" && $.operation == "company_lookup")'
+    "Search indexed fields with == and &&; field types and availability below"
   ).option(
     "--payloads",
-    "Include full stored payloads (up to 10 events and 16 MiB)"
+    "Search with canonical eventPayload or receipt payload; max 10 events, 16 MiB"
   ).option("--cursor <token>", "Continue a bounded event search").option(
     "--runtime-namespace <name>",
     "Search an explicitly authorized Preview namespace"
@@ -37235,11 +37480,11 @@ async function handlePlaySharePublish(args) {
           ok: false,
           code: "NO_SUCCESSFUL_RUN",
           message,
-          next: `deepline plays run ${name} --wait`
+          next: `deepline plays run ${name}`
         });
       } else {
         console.error(message);
-        console.error(`  deepline plays run ${name} --wait`);
+        console.error(`  deepline plays run ${name}`);
       }
       return 7;
     }
@@ -42225,7 +42470,7 @@ function registerEnrichCommand(program) {
     "--open",
     "Open the generated play page in a browser after the run starts."
   ).addOption(
-    new Option3(
+    new Option4(
       "--no-open [legacy-value]",
       "Removed legacy option"
     ).hideHelp()
@@ -42615,7 +42860,7 @@ function registerExecutionsCommands(program) {
 }
 
 // src/cli/commands/feedback.ts
-import { Option as Option4 } from "commander";
+import { Option as Option5 } from "commander";
 import { readFileSync as readFileSync10 } from "fs";
 async function handleFeedback(text, options) {
   const message = resolveFeedbackText(text, options.file);
@@ -42681,7 +42926,7 @@ Notes:
   to submit the report.
 
 Examples:
-  deepline feedback send "plays run failed after upload" --command "deepline plays run my.play.ts --watch" --error-outcome terminal
+  deepline feedback send "plays run failed after upload" --command "deepline plays run my.play.ts" --error-outcome terminal
   deepline feedback send "unexpected billing output" --payload '{"command":"billing usage"}' --json
 `
   );
@@ -42693,10 +42938,10 @@ Examples:
   deepline feedback send --file incident.md --requested --json
   cat incident.md | deepline feedback send --requested --json
   deepline feedback send "tools search returned stale results" --requested --json
-  deepline feedback send "plays run failed after upload" --command "deepline plays run my.play.ts --watch" --error-outcome terminal
+  deepline feedback send "plays run failed after upload" --command "deepline plays run my.play.ts" --error-outcome terminal
 `
   ).argument("[text]", "Feedback text").option("--file <path>", "Read feedback text from a file, or - for stdin").option("--command <command>", "Command that reproduced the issue").option("--payload <payload>", "JSON or plain-text payload for the repro").addOption(
-    new Option4(
+    new Option5(
       "--error-outcome <outcome>",
       "Error impact on the task: terminal or continued"
     ).choices(["terminal", "continued"])
@@ -54001,7 +54246,7 @@ Examples:
 }
 
 // src/cli/commands/tools.ts
-import { Option as Option5 } from "commander";
+import { Option as Option6 } from "commander";
 import {
   chmodSync,
   existsSync as existsSync20,
@@ -55031,7 +55276,7 @@ function isMissingToolMetadataError(error) {
 function playAliasToolErrorMessage(toolId, play) {
   const playName = play.reference ?? play.name;
   return `${toolId} is a play, not a tool.
-Use: deepline plays run ${playName} --input '{...}' --watch
+Use: deepline plays run ${playName} --input '{...}'
 Inspect its schema with: deepline plays describe ${playName} --json`;
 }
 function printPlayAliasToolError(toolId, play) {
@@ -55063,11 +55308,11 @@ function playRunCommandForTool(tool, toolId, input2) {
   const playReference = playReferenceForTool(tool);
   if (!playReference) return playSearchCommandForToolId(toolId);
   const inputArg = input2 === void 0 ? "'{...}'" : `'${JSON.stringify(input2)}'`;
-  return `deepline plays run ${playReference} --input ${inputArg} --watch`;
+  return `deepline plays run ${playReference} --input ${inputArg}`;
 }
 function playLikeToolExecuteErrorMessage(toolId, tool) {
   const playReference = tool ? playReferenceForTool(tool) : null;
-  const nextStep = playReference ? `Use: deepline plays run ${playReference} --input '{...}' --watch` : `Find the maintained workflow with: ${playSearchCommandForToolId(toolId)}`;
+  const nextStep = playReference ? `Use: deepline plays run ${playReference} --input '{...}'` : `Find the maintained workflow with: ${playSearchCommandForToolId(toolId)}`;
   return [
     `${toolId} is a workflow/play entry, not an atomic provider tool.`,
     nextStep,
@@ -55243,12 +55488,12 @@ Examples:
     "--examples-only",
     "Only print runnable examples and sample payloads"
   ).option("--getters-only", "Only print extracted list/value getters").addOption(
-    new Option5(
+    new Option6(
       "--compact",
       "Compatibility alias for the default compact view"
     ).hideHelp()
   ).addOption(
-    new Option5(
+    new Option6(
       "--contract-json",
       "Compatibility alias for compact contract JSON"
     ).hideHelp()
@@ -58263,7 +58508,7 @@ async function main() {
   if (printStartupPhase) {
     progress?.phase("loading deepline cli");
   }
-  const program = new Command6();
+  const program = new Command7();
   program.name("deepline").description(
     "Deepline CLI \u2014 GTM enrichment tools, plays, and runs from your terminal."
   ).version(SDK_VERSION, "-v, --version", "Show version").exitOverride().showHelpAfterError().showSuggestionAfterError(true).addHelpText(