deepline 0.3.271 → 0.3.273

package/dist/cli/index.js

@@ -3512,7 +3512,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.271",
+  version: "0.3.273",
   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
@@ -5226,6 +5226,425 @@ var ledgerIngressRedactor = createSecretRedactionContext();
 var utf8Encoder = new TextEncoder();
 var PLAY_DATASET_BRAND = Symbol.for("deepline.play.dataset");
 
+// ../play-runtime/run-event-catalog.ts
+var RUN_EVENT_KIND = {
+  runCreated: "run.created",
+  runStarted: "run.started",
+  runWaiting: "run.waiting",
+  runResumed: "run.resumed",
+  runCompleted: "run.completed",
+  runFailed: "run.failed",
+  runCancelled: "run.cancelled",
+  stepStarted: "step.started",
+  stepProgress: "step.progress",
+  stepCompleted: "step.completed",
+  stepFailed: "step.failed",
+  stepSkipped: "step.skipped",
+  logAppended: "log.appended",
+  datasetLifecycle: "dataset.lifecycle",
+  activityObserved: "activity.observed",
+  workCounters: "work.counters"
+};
+var SEARCHABLE_EVENT_FIELDS = [
+  "kind",
+  "runId",
+  "playName",
+  "source",
+  "occurredAt"
+];
+var RUN_SNAPSHOT_DESTINATION = {
+  searchIndex: "planet_scale_runtime_event_index",
+  markedRunStore: "planet_scale",
+  planetScaleContent: "event_payload",
+  convexProjection: "run_snapshot",
+  convexRetainedFacts: ["saved_play_rollup_if_eligible"],
+  legacyConvexDestination: "run_ledger_history",
+  explanation: "PlanetScale retains the complete event. Convex reduces it into bounded current run state and keeps only selected saved-Play rollup facts when eligible; unmarked legacy runs retain Convex event history."
+};
+var RUN_CREATED_DESTINATION = {
+  ...RUN_SNAPSHOT_DESTINATION,
+  convexRetainedFacts: ["admission_fence", "saved_play_rollup_if_eligible"],
+  explanation: "PlanetScale retains the complete event. Convex uses it for the live run snapshot, retains the admission fence, and may retain a saved-Play rollup fact; unmarked legacy runs retain Convex event history."
+};
+var RUN_LOG_DESTINATION = {
+  searchIndex: "planet_scale_runtime_event_index",
+  markedRunStore: "planet_scale",
+  planetScaleContent: "log_body",
+  convexProjection: null,
+  convexRetainedFacts: [],
+  legacyConvexDestination: "run_log_stream",
+  explanation: "PlanetScale retains the canonical log line and its search metadata. Marked-run log bodies are not copied into Convex; unmarked legacy runs continue to use the Convex Run Log Stream."
+};
+var RUN_EVENT_KIND_CATALOG = {
+  [RUN_EVENT_KIND.runCreated]: {
+    description: "The run was admitted and received its run ID.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ["run.created"],
+    destination: RUN_CREATED_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.runCreated,
+      seq: 1
+    }
+  },
+  [RUN_EVENT_KIND.runStarted]: {
+    description: "The run began execution.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ["run.started"],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.runStarted,
+      seq: 2
+    }
+  },
+  [RUN_EVENT_KIND.runWaiting]: {
+    description: "The run entered a durable wait.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ["run.waiting"],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.runWaiting,
+      waitKind: "sleep"
+    }
+  },
+  [RUN_EVENT_KIND.runResumed]: {
+    description: "The run resumed after a durable wait.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ["run.resumed"],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.runResumed
+    }
+  },
+  [RUN_EVENT_KIND.runCompleted]: {
+    description: "The run completed successfully.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ["run.completed", "runner.logs"],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.runCompleted
+    }
+  },
+  [RUN_EVENT_KIND.runFailed]: {
+    description: "The run ended with a failure.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ["run.failed", "runner.logs"],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.runFailed,
+      error: "Request timed out"
+    }
+  },
+  [RUN_EVENT_KIND.runCancelled]: {
+    description: "The run was cancelled.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ["run.cancelled"],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.runCancelled
+    }
+  },
+  [RUN_EVENT_KIND.stepStarted]: {
+    description: "A named step began execution.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      "run.events",
+      "run.completed",
+      "run.failed",
+      "runner.logs"
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.stepStarted,
+      stepId: "lookup"
+    }
+  },
+  [RUN_EVENT_KIND.stepProgress]: {
+    description: "A named step reported progress.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      "run.events",
+      "run.completed",
+      "run.failed",
+      "runner.logs"
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.stepProgress,
+      stepId: "lookup"
+    }
+  },
+  [RUN_EVENT_KIND.stepCompleted]: {
+    description: "A named step completed.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      "run.events",
+      "run.completed",
+      "run.failed",
+      "runner.logs"
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.stepCompleted,
+      stepId: "lookup"
+    }
+  },
+  [RUN_EVENT_KIND.stepFailed]: {
+    description: "A named step failed.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      "run.events",
+      "run.completed",
+      "run.failed",
+      "runner.logs"
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.stepFailed,
+      stepId: "lookup"
+    }
+  },
+  [RUN_EVENT_KIND.stepSkipped]: {
+    description: "A named step was skipped.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      "run.events",
+      "run.completed",
+      "run.failed",
+      "runner.logs"
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.stepSkipped,
+      stepId: "lookup"
+    }
+  },
+  [RUN_EVENT_KIND.logAppended]: {
+    description: "A text log line was appended to the unified run history and log view.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      "run.events",
+      "run.waiting",
+      "run.resumed",
+      "run.completed",
+      "run.failed",
+      "runner.logs",
+      "run.wait_timeout"
+    ],
+    destination: RUN_LOG_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.logAppended,
+      lines: ["Waiting for integration_event:contact.updated."]
+    }
+  },
+  [RUN_EVENT_KIND.datasetLifecycle]: {
+    description: "A run dataset was registered, made available, or failed.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      "run.events",
+      "run.completed",
+      "run.failed",
+      "runner.logs"
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.datasetLifecycle,
+      phase: "available"
+    }
+  },
+  [RUN_EVENT_KIND.activityObserved]: {
+    description: "The runtime recorded an activity observation.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      "run.events",
+      "run.completed",
+      "run.failed",
+      "runner.logs"
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.activityObserved
+    }
+  },
+  [RUN_EVENT_KIND.workCounters]: {
+    description: "A work segment reported logical call, provider request, and rate-limit counters.",
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      "run.events",
+      "run.completed",
+      "run.failed",
+      "runner.logs"
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: "play/enrich/run/abc123",
+      type: RUN_EVENT_KIND.workCounters,
+      attempt: 1,
+      logicalCalls: 4,
+      providerRequests: 4,
+      provider429s: 0,
+      final: true
+    }
+  }
+};
+var RUN_EVENT_KINDS = Object.freeze(
+  Object.keys(RUN_EVENT_KIND_CATALOG)
+);
+var RUN_SCHEDULER_OUTBOX_EVENT_TYPE = {
+  runCreated: RUN_EVENT_KIND.runCreated,
+  runStarted: RUN_EVENT_KIND.runStarted,
+  runWaiting: RUN_EVENT_KIND.runWaiting,
+  runResumed: RUN_EVENT_KIND.runResumed,
+  runCompleted: RUN_EVENT_KIND.runCompleted,
+  runFailed: RUN_EVENT_KIND.runFailed,
+  runCancelled: RUN_EVENT_KIND.runCancelled,
+  runEvents: "run.events",
+  runnerLogs: "runner.logs",
+  runWaitTimeout: "run.wait_timeout"
+};
+var RUN_SCHEDULER_OUTBOX_EVENT_TYPES = Object.freeze(
+  Object.values(RUN_SCHEDULER_OUTBOX_EVENT_TYPE)
+);
+var RUN_SCHEDULER_OUTBOX_START_EVENT_TYPES = [
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCreated,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runStarted
+];
+var RUN_SCHEDULER_OUTBOX_PREFIX_STOP_EVENT_TYPES = [
+  ...RUN_SCHEDULER_OUTBOX_START_EVENT_TYPES,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runEvents
+];
+var RUN_SCHEDULER_OUTBOX_TERMINAL_EVENT_TYPES = [
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCompleted,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runFailed,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCancelled
+];
+var RUN_EVENT_CONVEX_INTERNAL_KIND = {
+  rollupMembershipAdded: "rollup.membership.added",
+  rollupMembershipRemoved: "rollup.membership.removed"
+};
+var RUN_RECEIPT_SEARCH_KIND = {
+  completed: "receipt.completed",
+  failed: "receipt.failed",
+  skipped: "receipt.skipped"
+};
+var RUN_RECEIPT_SEARCH_KIND_CATALOG = {
+  [RUN_RECEIPT_SEARCH_KIND.completed]: {
+    description: "A durable work receipt completed.",
+    searchIndex: "planet_scale_runtime_event_index",
+    payloadStore: "authoritative_work_receipt"
+  },
+  [RUN_RECEIPT_SEARCH_KIND.failed]: {
+    description: "A durable work receipt failed.",
+    searchIndex: "planet_scale_runtime_event_index",
+    payloadStore: "authoritative_work_receipt"
+  },
+  [RUN_RECEIPT_SEARCH_KIND.skipped]: {
+    description: "A durable work receipt was skipped.",
+    searchIndex: "planet_scale_runtime_event_index",
+    payloadStore: "authoritative_work_receipt"
+  }
+};
+var RUN_EVENT_SEARCH_FALLBACK_KIND = "runtime.event";
+var RUN_EVENT_SEARCH_KIND_VALUES = Object.freeze([
+  ...RUN_EVENT_KINDS,
+  ...Object.keys(RUN_RECEIPT_SEARCH_KIND_CATALOG),
+  RUN_EVENT_SEARCH_FALLBACK_KIND
+]);
+var RUN_EVENT_TERMINAL_KIND_VALUES = [
+  RUN_EVENT_KIND.runCompleted,
+  RUN_EVENT_KIND.runFailed,
+  RUN_EVENT_KIND.runCancelled
+];
+var RUN_LOG_RETENTION_MAX_BYTES = 5 * 1024 * 1024;
+function sqlStringLiteral(value) {
+  return "'" + value.replaceAll("'", "''") + "'";
+}
+var RUN_EVENT_KNOWN_KIND_SQL_LIST = RUN_EVENT_KINDS.map(sqlStringLiteral).join(", ");
+var RUN_EVENT_LIFECYCLE_KIND_SQL_LIST = [
+  RUN_EVENT_KIND.runCreated,
+  RUN_EVENT_KIND.runStarted,
+  RUN_EVENT_KIND.runWaiting,
+  RUN_EVENT_KIND.runResumed,
+  RUN_EVENT_KIND.runCompleted,
+  RUN_EVENT_KIND.runFailed,
+  RUN_EVENT_KIND.runCancelled
+].map(sqlStringLiteral).join(", ");
+var RUN_EVENT_SNAPSHOT_KIND_SQL_LIST = RUN_EVENT_KINDS.filter(
+  (kind) => kind !== RUN_EVENT_KIND.logAppended
+).map(sqlStringLiteral).join(", ");
+var RUN_EVENT_KIND_SQL_LITERAL = {
+  runCreated: sqlStringLiteral(RUN_EVENT_KIND.runCreated),
+  runStarted: sqlStringLiteral(RUN_EVENT_KIND.runStarted),
+  runWaiting: sqlStringLiteral(RUN_EVENT_KIND.runWaiting),
+  runResumed: sqlStringLiteral(RUN_EVENT_KIND.runResumed),
+  runCompleted: sqlStringLiteral(RUN_EVENT_KIND.runCompleted),
+  runFailed: sqlStringLiteral(RUN_EVENT_KIND.runFailed),
+  runCancelled: sqlStringLiteral(RUN_EVENT_KIND.runCancelled),
+  stepStarted: sqlStringLiteral(RUN_EVENT_KIND.stepStarted),
+  stepProgress: sqlStringLiteral(RUN_EVENT_KIND.stepProgress),
+  stepCompleted: sqlStringLiteral(RUN_EVENT_KIND.stepCompleted),
+  stepFailed: sqlStringLiteral(RUN_EVENT_KIND.stepFailed),
+  stepSkipped: sqlStringLiteral(RUN_EVENT_KIND.stepSkipped),
+  logAppended: sqlStringLiteral(RUN_EVENT_KIND.logAppended),
+  datasetLifecycle: sqlStringLiteral(RUN_EVENT_KIND.datasetLifecycle),
+  activityObserved: sqlStringLiteral(RUN_EVENT_KIND.activityObserved),
+  workCounters: sqlStringLiteral(RUN_EVENT_KIND.workCounters)
+};
+var RUN_SCHEDULER_OUTBOX_EVENT_TYPE_SQL_LITERAL = {
+  runCreated: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCreated),
+  runStarted: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runStarted),
+  runWaiting: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runWaiting),
+  runResumed: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runResumed),
+  runCompleted: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCompleted),
+  runFailed: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runFailed),
+  runCancelled: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCancelled),
+  runEvents: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runEvents),
+  runnerLogs: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runnerLogs),
+  runWaitTimeout: sqlStringLiteral(
+    RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runWaitTimeout
+  )
+};
+var RUN_EVENT_CONVEX_INTERNAL_KIND_SQL_LITERAL = {
+  rollupMembershipAdded: sqlStringLiteral(
+    RUN_EVENT_CONVEX_INTERNAL_KIND.rollupMembershipAdded
+  ),
+  rollupMembershipRemoved: sqlStringLiteral(
+    RUN_EVENT_CONVEX_INTERNAL_KIND.rollupMembershipRemoved
+  )
+};
+var RUN_EVENT_TERMINAL_LOG_CARRIER_SQL_LIST = [
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCompleted,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runFailed,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runnerLogs
+].map(sqlStringLiteral).join(", ");
+var RUN_SCHEDULER_OUTBOX_TERMINAL_EVENT_TYPE_SQL_LIST = [
+  ...RUN_SCHEDULER_OUTBOX_TERMINAL_EVENT_TYPES
+].map(sqlStringLiteral).join(", ");
+var RUN_EVENT_SEARCH_FALLBACK_KIND_SQL_LITERAL = sqlStringLiteral(
+  RUN_EVENT_SEARCH_FALLBACK_KIND
+);
+
+// ../play-runtime/run-ledger.ts
+var TERMINAL_STATUS_BY_EVENT_TYPE = {
+  [RUN_EVENT_KIND.runCompleted]: "completed",
+  [RUN_EVENT_KIND.runFailed]: "failed",
+  [RUN_EVENT_KIND.runCancelled]: "cancelled"
+};
+
 // ../play-runtime/run-lifecycle-policy.ts
 var TERMINAL_PLAY_RUN_STATUSES = /* @__PURE__ */ new Set([
   "completed",
@@ -7949,7 +8368,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)
@@ -8005,7 +8424,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:
    *
@@ -8084,7 +8503,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({
@@ -15244,6 +15663,233 @@ function registerPlayTriggerConfigCommands(plays) {
 // src/cli/commands/play.ts
 var import_node_crypto7 = require("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, --log-level, --logs and --debug 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."
+    ],
+    commands: [
+      `deepline runs logs --kind receipt.failed --where '$.status == "failed"' --payloads --json`,
+      `deepline runs logs <run-id> --where '$.source == "worker" && $.producerAttempt == 1' --json`,
+      `deepline runs logs --kind activity.observed --where '$.provider == "<returned-provider>" && $.operation == "<returned-operation>"' --json`,
+      `deepline runs logs --kind log.appended --where '$.context.<authored-key> == "<recorded-value>"' --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)}`);
@@ -36375,44 +37021,21 @@ 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.
-
-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(
+  ).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>",
+    "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"
@@ -39442,7 +40065,7 @@ function enrichReportJson(report) {
     } : {}
   };
 }
-function sqlStringLiteral(value) {
+function sqlStringLiteral2(value) {
   return `'${value.replace(/'/g, "''")}'`;
 }
 function failureAliasFromCellMeta(cellMeta) {
@@ -39537,7 +40160,7 @@ async function collectCustomerDbFailureJobs(input2) {
   const aliasIndexByName = new Map(
     fallbackAliases.map((spec, index) => [normalizeAlias2(spec.alias), index])
   );
-  const sql = `select _input_index, _status, _error, _cell_meta from ${customerDb.sqlQualifiedTableName} where _run_id = ${sqlStringLiteral(customerDb.runId)} and (_error is not null or lower(coalesce(_status, '')) in ('failed', 'error')) order by _input_index limit 1000`;
+  const sql = `select _input_index, _status, _error, _cell_meta from ${customerDb.sqlQualifiedTableName} where _run_id = ${sqlStringLiteral2(customerDb.runId)} and (_error is not null or lower(coalesce(_status, '')) in ('failed', 'error')) order by _input_index limit 1000`;
   const retryDelays = enrichCustomerDbFailureLookupRetryDelaysMs();
   let lastError = null;
   let attempts = 0;