deepline 0.1.235 → 0.1.237

package/dist/bundling-sources/apps/play-runner-workers/src/entry.ts

@@ -3828,6 +3828,9 @@ function createWorkerPacingResolver(req: RunRequest): WorkerPacingResolver {
     if (builtin) {
       return Promise.resolve({
         ...builtin,
+        // Builtin pacing has no per-org coordinator rate scope. Keep the
+        // required resolver contract explicit so the Governor treats it as
+        // intentionally unscoped rather than receiving a malformed policy.
         r: null,
         retrySafeTransientHttp: false,
       });

package/dist/bundling-sources/sdk/src/release.ts

@@ -108,10 +108,10 @@ export const SDK_RELEASE = {
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
   // 0.1.220 deprecates SDK CLI versions below 0.1.219 and updates them
   // automatically without blocking their current command.
-  version: '0.1.235',
+  version: '0.1.237',
   apiContract: '2026-06-dataset-handle-results-hard-cutover',
   supportPolicy: {
-    latest: '0.1.235',
+    latest: '0.1.237',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.219',
     commandMinimumSupported: [

package/dist/bundling-sources/shared_libs/play-runtime/durable-receipt-execution.ts

@@ -12,6 +12,7 @@ import {
   isPlayRowExecutionSuspendedError,
 } from './suspension';
 import { getToolHttpErrorReceiptFailureKind } from './tool-http-errors';
+import { isLegacyRepairableWorkReceiptError } from './work-receipt-state-machine';
 import type { WorkReceiptFailureKind } from './work-receipts';
 import {
   PLAY_RUNTIME_WORK_RECEIPT_LEASE_TTL_MS,
@@ -63,8 +64,24 @@ export function runtimeReceiptFailureKindForError(
   const toolFailureKind = getToolHttpErrorReceiptFailureKind(error);
   if (toolFailureKind) return toolFailureKind;
 
-  return isPlayExecutionSuspendedError(error) ||
+  if (
+    isPlayExecutionSuspendedError(error) ||
     isPlayRowExecutionSuspendedError(error)
+  ) {
+    return 'repairable';
+  }
+
+  // Transport/timeout failures never reach a `ToolHttpError` (there was no HTTP
+  // response to classify), so they would otherwise default to `terminal` and
+  // poison the durable receipt: the next run would replay the cached transport
+  // failure instead of re-executing. These are transient infra failures, so
+  // mark them repairable. `isLegacyRepairableWorkReceiptError` already encodes
+  // the exact transient-string contract (5xx, "transport failed calling",
+  // "runtime api call timed out") while excluding hard billing caps, and the
+  // read-side SQL predicate uses the same rules, so write and read stay aligned.
+  const message =
+    error instanceof Error ? error.message : error != null ? String(error) : '';
+  return isLegacyRepairableWorkReceiptError(message)
     ? 'repairable'
     : 'terminal';
 }

package/dist/bundling-sources/shared_libs/play-runtime/output-size-limits.ts

@@ -1,6 +1,19 @@
 const encoder = typeof TextEncoder === 'undefined' ? null : new TextEncoder();
 
 export const TERMINAL_RUN_RESULT_MAX_BYTES = 2_500_000;
+/**
+ * Convex hard-caps a single document at 1 MiB and rejects nesting deeper than
+ * 16 levels. A run-ledger `run.completed` / `run.failed` event embeds its
+ * `result` inside one `playRunEvents` document, so the ledger-bound result must
+ * stay comfortably under that ceiling (the event also carries seq/type/
+ * timestamps and the surrounding doc envelope). Keep well below 1 MiB so no
+ * single event can wedge the append mutation with `Value is too large (>1MiB)`.
+ * Historically a failed run embedded its full `PlayRunnerResult` — including a
+ * `checkpoint` whose `completedToolBatches[*].toolResponse.raw` held megabytes
+ * of provider payload — which is durable in scheduler Postgres and never read
+ * back from Convex, yet deterministically wedged the append.
+ */
+export const LEDGER_TERMINAL_RESULT_MAX_BYTES = 768 * 1024;
 export const CUSTOMER_OUTPUT_VALUE_MAX_BYTES = 1 * 1024 * 1024;
 export const CUSTOMER_OUTPUT_TOTAL_MAX_BYTES = 2 * 1024 * 1024;
 /** Inline Postgres receipt contract: one serialized output is at most 10 MiB. */
@@ -86,6 +99,81 @@ export function persistableTerminalRunResult(value: unknown): unknown {
   return valueWithinJsonByteLimit(value, TERMINAL_RUN_RESULT_MAX_BYTES);
 }
 
+/**
+ * Replay-only keys a terminal `PlayRunnerResult` carries for the scheduler
+ * (Postgres) data plane. These are NEVER read back from the Convex run ledger:
+ * resume rehydrates the checkpoint/suspension from scheduler Postgres
+ * (`work_runs.checkpoint_json` / `suspension_json`), and customer reads use the
+ * run's `output`. Embedding them in a `playRunEvents` document only bloats the
+ * write and can exceed Convex's 1 MiB / 16-level document limits.
+ */
+const LEDGER_STRIPPED_TERMINAL_RESULT_KEYS = [
+  'checkpoint',
+  'suspension',
+] as const;
+
+/** A tiny reference descriptor left in place of a dropped over-limit result. */
+export type LedgerTerminalResultRef = {
+  __kind: 'deepline.ledger_terminal_result_ref.v1';
+  /** Where the full terminal result is durably stored. */
+  store: 'scheduler_postgres';
+  /** Column on the scheduler `work_runs` row that holds the full result. */
+  key: 'terminal_result_json';
+  /** Serialized byte size of the result that was elided from the ledger. */
+  bytes: number;
+  reason: 'terminal_result_exceeds_ledger_limit';
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Shape a terminal run result for the Convex run ledger. Control-plane only:
+ *
+ * 1. Strip replay-only keys ({@link LEDGER_STRIPPED_TERMINAL_RESULT_KEYS}) from
+ *    the top-level result object — the scheduler Postgres data plane owns them.
+ * 2. If what remains still exceeds {@link LEDGER_TERMINAL_RESULT_MAX_BYTES},
+ *    replace the whole result with a {@link LedgerTerminalResultRef} pointing at
+ *    the durable scheduler copy, so the ledger event stays small and the
+ *    Convex append cannot wedge on an oversized/over-nested document.
+ *
+ * The full result (including its checkpoint) remains durable in scheduler
+ * Postgres regardless; this only governs what the ledger embeds.
+ */
+export function terminalRunResultForLedger(value: unknown): unknown {
+  if (value === undefined || value === null) {
+    return value;
+  }
+  let candidate = value;
+  if (isPlainObject(value)) {
+    const stripped: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value)) {
+      if (
+        (LEDGER_STRIPPED_TERMINAL_RESULT_KEYS as readonly string[]).includes(
+          key,
+        )
+      ) {
+        continue;
+      }
+      stripped[key] = entry;
+    }
+    candidate = stripped;
+  }
+  const bytes = jsonByteLength(candidate);
+  if (bytes <= LEDGER_TERMINAL_RESULT_MAX_BYTES) {
+    return candidate;
+  }
+  const ref: LedgerTerminalResultRef = {
+    __kind: 'deepline.ledger_terminal_result_ref.v1',
+    store: 'scheduler_postgres',
+    key: 'terminal_result_json',
+    bytes,
+    reason: 'terminal_result_exceeds_ledger_limit',
+  };
+  return ref;
+}
+
 export function assertCustomerOutputValueWithinLimit(input: {
   value: unknown;
   path: string;

package/dist/bundling-sources/shared_libs/play-runtime/receipt-sql.ts

@@ -1,6 +1,16 @@
 import { RECEIPT_STATUS_CODE } from './receipt-status';
 import { workReceiptFailureKindCode } from './work-receipts';
 
+// This predicate MUST stay behaviorally identical to
+// `isLegacyRepairableWorkReceiptError` in ./work-receipt-state-machine.ts.
+// Write-side classification and this read-side reclaim gate share one contract:
+// a receipt is repairable if its failure_kind is repairable, OR it is a legacy
+// terminal receipt whose error text proves a transient-class failure (5xx,
+// transport, timeout, or a transient billing-plane outage). The
+// billing_unavailable clause recovers the poisoned backlog written during a
+// billing-plane incident, where transient 503s were formatted with the hard
+// "billing cap" template — it is checked BEFORE the hard-billing exclusions so
+// those receipts re-execute on the next run instead of replaying the failure.
 export function workReceiptRepairableFailurePredicateSql(
   receiptTable: string,
 ): string {
@@ -9,13 +19,20 @@ export function workReceiptRepairableFailurePredicateSql(
     OR (
       ${receiptTable}.failure_kind = ${workReceiptFailureKindCode('terminal')}::smallint
       AND ${receiptTable}.error IS NOT NULL
-      AND lower(${receiptTable}.error) NOT LIKE '%billing cap%'
-      AND lower(${receiptTable}.error) NOT LIKE '%insufficient credits%'
-      AND lower(${receiptTable}.error) NOT LIKE '%monthly billing limit%'
       AND (
-        ${receiptTable}.error ~* '(^|[^0-9])5[0-9]{2}([^0-9]|$)'
-        OR lower(${receiptTable}.error) LIKE '%transport failed calling%'
-        OR lower(${receiptTable}.error) LIKE '%runtime api call timed out%'
+        lower(${receiptTable}.error) LIKE '%billing_unavailable%'
+        OR lower(${receiptTable}.error) LIKE '%billing is temporarily unavailable%'
+        OR lower(${receiptTable}.error) LIKE '%billing temporarily unavailable%'
+        OR (
+          lower(${receiptTable}.error) NOT LIKE '%billing cap%'
+          AND lower(${receiptTable}.error) NOT LIKE '%insufficient credits%'
+          AND lower(${receiptTable}.error) NOT LIKE '%monthly billing limit%'
+          AND (
+            ${receiptTable}.error ~* '(^|[^0-9])5[0-9]{2}([^0-9]|$)'
+            OR lower(${receiptTable}.error) LIKE '%transport failed calling%'
+            OR lower(${receiptTable}.error) LIKE '%runtime api call timed out%'
+          )
+        )
       )
     )
   )`;

package/dist/bundling-sources/shared_libs/play-runtime/tool-http-errors.ts

@@ -52,10 +52,40 @@ function isInsufficientCreditsBilling(
   return billing?.kind === 'insufficient_credits';
 }
 
+/**
+ * A transient failure of the Deepline billing PLANE (Convex outage, OCC
+ * exhaustion) surfaced as HTTP 503 `BILLING_UNAVAILABLE` with `retryable: true`
+ * and `failure_description` stating no credits were charged. This is NOT a hard
+ * credit/cap denial: a funded org is temporarily blocked because our billing
+ * store hiccuped, so it must be repairable on the next run rather than cached as
+ * a terminal failure. See `billingUnavailableResponse` in
+ * src/lib/integrations/execute-billing.ts. This class is the exact incident
+ * poison closed by issues #2561/#2706: without this carve-out a billing-plane
+ * outage classifies every affected tool call as `hard_billing_error` ->
+ * `terminal` and the next run replays the cached failure instead of retrying.
+ */
+export function isTransientBillingFailurePayload(
+  payload: Record<string, unknown> | null,
+): boolean {
+  if (!payload) return false;
+  const code = String(payload.code ?? payload.error_code ?? '').toUpperCase();
+  if (code === 'BILLING_UNAVAILABLE') return true;
+  // Any billing-origin payload that explicitly declares itself retryable is a
+  // billing-infra hiccup, never a hard denial (denials are never retryable).
+  const category = String(
+    payload.error_category ?? payload.errorCategory ?? '',
+  ).toLowerCase();
+  return category === 'billing' && payload.retryable === true;
+}
+
 function isHardBillingFailurePayload(
   payload: Record<string, unknown> | null,
 ): payload is Record<string, unknown> {
   if (!payload) return false;
+  // Billing-plane outages (503 BILLING_UNAVAILABLE) are transient infra, not
+  // hard denials. Never let them reach the terminal, run-fatal hard-billing
+  // path — they must stay repairable so the next run retries.
+  if (isTransientBillingFailurePayload(payload)) return false;
   const category = String(
     payload.error_category ?? payload.errorCategory ?? '',
   ).toLowerCase();
@@ -100,6 +130,10 @@ function normalizeHardBillingPayload(
 function receiptFailureKindForToolErrorPayload(
   payload: Record<string, unknown> | null,
 ): WorkReceiptFailureKind {
+  // A transient billing-plane outage (503 BILLING_UNAVAILABLE) charged nothing
+  // and is explicitly retryable. It must be repairable so the next run
+  // re-executes instead of replaying the cached billing-infra failure.
+  if (isTransientBillingFailurePayload(payload)) return 'repairable';
   const code = getStringField(payload, 'code')?.toUpperCase();
   // A credential connection can be added or replaced between play runs. Keep
   // the failure terminal within its owning run, but let a later run reclaim

package/dist/bundling-sources/shared_libs/play-runtime/work-receipt-state-machine.ts

@@ -22,6 +22,21 @@ export function isLegacyRepairableWorkReceiptError(
 ): boolean {
   const message = error?.trim().toLowerCase() ?? '';
   if (!message) return false;
+  // Transient billing-PLANE outages (503 BILLING_UNAVAILABLE) were historically
+  // formatted with the hard "billing cap exceeded" template (see
+  // formatHardBillingFailureMessage), so the receipts written during a
+  // billing-plane incident carry a "billing cap" string even though they are
+  // retryable infra failures that charged nothing. Recognize them BEFORE the
+  // hard-billing exclusion below so the poisoned backlog re-executes on the next
+  // run instead of replaying the cached failure. Real hard denials never carry a
+  // BILLING_UNAVAILABLE code or "temporarily unavailable" text.
+  if (
+    message.includes('billing_unavailable') ||
+    message.includes('billing is temporarily unavailable') ||
+    message.includes('billing temporarily unavailable')
+  ) {
+    return true;
+  }
   if (
     message.includes('billing cap') ||
     message.includes('insufficient credits') ||

package/dist/cli/index.js

@@ -625,10 +625,10 @@ var SDK_RELEASE = {
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
   // 0.1.220 deprecates SDK CLI versions below 0.1.219 and updates them
   // automatically without blocking their current command.
-  version: "0.1.235",
+  version: "0.1.237",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.235",
+    latest: "0.1.237",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.219",
     commandMinimumSupported: [
@@ -1456,6 +1456,7 @@ function createSecretRedactionContext(initialValues = []) {
 
 // ../shared_libs/play-runtime/output-size-limits.ts
 var encoder = typeof TextEncoder === "undefined" ? null : new TextEncoder();
+var LEDGER_TERMINAL_RESULT_MAX_BYTES = 768 * 1024;
 var CUSTOMER_OUTPUT_VALUE_MAX_BYTES = 1 * 1024 * 1024;
 var CUSTOMER_OUTPUT_TOTAL_MAX_BYTES = 2 * 1024 * 1024;
 var RUNTIME_RECEIPT_OUTPUT_MAX_BYTES = 10 * 1024 * 1024;
@@ -12080,6 +12081,9 @@ function getRunIdFromLiveEvent(event) {
   const packageRunId = getRunRecordFromPackage(payload)?.id;
   return typeof packageRunId === "string" && packageRunId.trim() ? packageRunId : null;
 }
+function eventConfirmsPlayRunLaunch(event) {
+  return event.type === "play.run.status" && getEventPayload(event).launchConfirmed === true;
+}
 function getStatusFromLiveEvent(event) {
   if (event.type !== "play.run.status" && event.type !== "play.run.snapshot" && event.type !== "play.run.final_status") {
     return null;
@@ -12506,70 +12510,6 @@ async function waitForPlayCompletionByStream(input2) {
     }
     return null;
   };
-  const watchViaObserveTransport = async () => {
-    const controller = new AbortController();
-    let timedOut = false;
-    const remaining = remainingWaitMs();
-    const timeout = remaining === null ? null : setTimeout(
-      () => {
-        timedOut = true;
-        controller.abort();
-      },
-      Math.max(1, remaining)
-    );
-    try {
-      for await (const event of input2.client.observeRunEvents(
-        input2.workflowId,
-        {
-          signal: controller.signal,
-          fallback: "none",
-          onNotice: input2.jsonOutput ? void 0 : (message) => input2.progress.writeLine(message)
-        }
-      )) {
-        const terminal2 = await handleLiveEvent(event);
-        if (terminal2) {
-          return terminal2;
-        }
-      }
-    } finally {
-      if (timeout) {
-        clearTimeout(timeout);
-      }
-    }
-    const terminal = await fetchTerminalStatus();
-    if (terminal) {
-      return terminal;
-    }
-    if (timedOut) {
-      assertPlayWaitNotTimedOut({ ...input2, lastPhase });
-    }
-    throw new DeeplineError(
-      `Run observation for ${input2.workflowId} ended before a terminal status.`,
-      void 0,
-      "PLAY_LIVE_STREAM_ENDED",
-      { runId: input2.workflowId, workflowId: input2.workflowId }
-    );
-  };
-  try {
-    return await watchViaObserveTransport();
-  } catch (error) {
-    if (!(error instanceof RunObserveTransportUnavailableError)) {
-      throw error;
-    }
-    if (!input2.jsonOutput) {
-      input2.progress.writeLine(
-        `[play watch] live subscription unavailable (${error.reason}); falling back to SSE tail (support window, ADR-0008)`
-      );
-    }
-    recordCliTrace({
-      phase: "cli.play_observe_transport_fallback",
-      ms: Date.now() - input2.startedAt,
-      ok: true,
-      playName: input2.playName,
-      workflowId: input2.workflowId,
-      reason: error.reason
-    });
-  }
   const streamOneWindow = async () => {
     const controller = new AbortController();
     let timedOut = false;
@@ -12702,6 +12642,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
   let launchedRevisionId = input2.request.revisionId?.trim() || null;
   let eventCount = 0;
   let firstRunIdMs = null;
+  let launchConfirmed = false;
   let lastPhase = null;
   const timeout = input2.waitTimeoutMs === null ? null : setTimeout(
     () => {
@@ -12752,6 +12693,9 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
           input2.onRunStarted?.(eventRunId);
         }
       }
+      if (eventConfirmsPlayRunLaunch(event) && eventRunId === lastKnownWorkflowId) {
+        launchConfirmed = true;
+      }
       const workflowId = lastKnownWorkflowId || "pending";
       if (workflowId !== "pending" && !emittedDashboardUrl) {
         if (!input2.jsonOutput) {
@@ -12828,6 +12772,16 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
       const finalStatus = getFinalStatusFromLiveEvent(event);
       if (finalStatus) {
         lastKnownWorkflowId ||= finalStatus.runId ?? "";
+        if (finalStatus.status === "failed" && !finalStatus.runId) {
+          return {
+            ...finalStatus,
+            runId: "pending",
+            name: input2.playName,
+            playName: input2.playName,
+            dashboardUrl,
+            ...launchedRevisionId ? { revisionId: launchedRevisionId } : {}
+          };
+        }
         const canonicalTerminal = input2.request.profile === "absurd" ? await fetchKnownTerminalStatus() : {
           ...finalStatus,
           dashboardUrl,
@@ -12859,6 +12813,34 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
         });
         return canonicalTerminal;
       }
+      if (lastKnownWorkflowId && launchConfirmed) {
+        if (timeout) {
+          clearTimeout(timeout);
+        }
+        controller.abort();
+        recordCliTrace({
+          phase: "cli.play_start_stream_handoff_to_tail",
+          ms: Date.now() - startedAt,
+          ok: true,
+          playName: input2.playName,
+          workflowId: lastKnownWorkflowId,
+          eventCount,
+          firstRunIdMs,
+          lastPhase
+        });
+        return waitForPlayCompletionByStream({
+          client: input2.client,
+          playName: input2.playName,
+          workflowId: lastKnownWorkflowId,
+          dashboardUrl,
+          jsonOutput: input2.jsonOutput,
+          emitLogs: input2.emitLogs,
+          waitTimeoutMs: input2.waitTimeoutMs,
+          startedAt,
+          state,
+          progress: input2.progress
+        });
+      }
     }
   } catch (error) {
     if (timedOut) {
@@ -14031,7 +14013,7 @@ function playRunPackageTextLedgerIncomplete(pkg) {
 }
 async function resolvePlayRunOutputStatus(input2) {
   const runId = input2.status.runId;
-  if (!runId) {
+  if (!runId || runId === "pending") {
     return input2.status;
   }
   const streamedPackage = getPlayRunPackage(input2.status);
@@ -26381,7 +26363,9 @@ function printPlayLikeToolExecuteError(toolId, tool) {
   console.error(playLikeToolExecuteErrorMessage(toolId, tool));
 }
 function registerToolsCommands(program) {
-  const tools = program.command("tools").description("Search, describe, and execute atomic provider tools.").addHelpText(
+  const tools = program.command("tools").description(
+    "Search by intent or structured filters, describe, and execute atomic provider tools."
+  ).addHelpText(
     "after",
     `
 Concepts:
@@ -26420,30 +26404,34 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  const addToolSearchCommand = (command) => command.description("Search available tools.").addHelpText(
+  const addToolSearchCommand = (command) => command.description(
+    "Search available tools by intent query or structured filters."
+  ).addHelpText(
     "after",
     `
 Notes:
   Ranked discovery for atomic provider/API operations. Results include tool ids
   that can be passed to deepline tools describe or deepline tools execute.
+  Provide a query, or omit it only when --categories and/or --search_terms is
+  supplied. Providing neither is a usage error. Both filters accept
+  comma-separated values. Use a provider name in the query; --prefix is not a
+  supported option.
   The grep alias is the same ranked retrieval surface with a more literal name
   for agents that are filtering a registry rather than choosing a workflow.
 
 Examples:
   deepline tools search email
+  deepline tools search --categories company_search --search_terms "investors,funding"
   deepline tools grep "company enrichment" --categories enrichment --json
   deepline tools search verifier --search-mode v2 --json
 `
   ).option(
     "--categories <categories>",
-    "Comma-separated categories to filter ranked search"
+    "Comma-separated categories; may be used without a query"
   ).option(
     "--search_terms <terms>",
-    "Structured search terms for ranked search"
-  ).option(
-    "--search-terms <terms>",
-    "Structured search terms for ranked search"
-  ).option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
+    "Comma-separated structured search terms; may be used without a query"
+  ).option("--search-terms <terms>", "Alias for --search_terms").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
     process.exitCode = await searchTools(query, {
       json: options.json,
       compact: options.compact,
@@ -28390,6 +28378,9 @@ function sdkSkillsVersionPath(baseUrl) {
 function legacySdkSkillsVersionPath(baseUrl) {
   return (0, import_node_path18.join)((0, import_node_path18.dirname)(sdkCliStateDirPath(baseUrl)), "sdk-skills", ".version");
 }
+function unavailableSkillsNoticePath(baseUrl) {
+  return (0, import_node_path18.join)(sdkCliStateDirPath(baseUrl), "skills-sync-unavailable-version");
+}
 function readSdkSkillsLocalVersion(baseUrl) {
   const pluginVersion = readPluginSkillsVersion();
   if (pluginVersion) return pluginVersion;
@@ -28407,6 +28398,29 @@ function writeLocalSkillsVersion(baseUrl, version) {
   (0, import_node_fs16.writeFileSync)(path, `${version}
 `, "utf-8");
 }
+function writeUnavailableSkillsNotice(baseUrl, remoteVersion, skillNames) {
+  const path = unavailableSkillsNoticePath(baseUrl);
+  try {
+    if ((0, import_node_fs16.existsSync)(path) && (0, import_node_fs16.readFileSync)(path, "utf-8").trim() === remoteVersion) {
+      return;
+    }
+    (0, import_node_fs16.mkdirSync)((0, import_node_path18.dirname)(path), { recursive: true });
+    (0, import_node_fs16.writeFileSync)(path, `${remoteVersion}
+`, "utf-8");
+  } catch {
+  }
+  const manualCommand = `npx ${buildSkillsInstallArgs(baseUrl, skillNames).join(" ")}`;
+  writeSdkSkillsStatusLine(
+    `Deepline agent skills are out of date, but neither \`bunx\` nor \`npx\` is available. Install Node.js/npm or Bun, then run:
+${manualCommand}`
+  );
+}
+function clearUnavailableSkillsNotice(baseUrl) {
+  try {
+    (0, import_node_fs16.unlinkSync)(unavailableSkillsNoticePath(baseUrl));
+  } catch {
+  }
+}
 function sortedUniqueSkillNames(names) {
   return [...new Set(names.map((name) => name.trim()).filter(Boolean))].sort(
     (a, b) => a.localeCompare(b)
@@ -28482,24 +28496,24 @@ function shellQuote5(arg) {
   return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
 function resolveSkillsInstallCommands(baseUrl, skillNames = DEFAULT_SDK_SKILL_NAMES) {
-  const npxArgs = buildSkillsInstallArgs(baseUrl, skillNames);
-  const npxInstall = {
-    command: "npx",
-    args: npxArgs,
-    manualCommand: `npx ${npxArgs.map(shellQuote5).join(" ")}`
-  };
+  const commands = [];
   if (hasCommand("bunx")) {
     const bunxArgs = buildBunxSkillsInstallArgs(baseUrl, skillNames);
-    return [
-      {
-        command: "bunx",
-        args: bunxArgs,
-        manualCommand: `bunx ${bunxArgs.map(shellQuote5).join(" ")}`
-      },
-      npxInstall
-    ];
+    commands.push({
+      command: "bunx",
+      args: bunxArgs,
+      manualCommand: `bunx ${bunxArgs.map(shellQuote5).join(" ")}`
+    });
   }
-  return [npxInstall];
+  if (hasCommand("npx")) {
+    const npxArgs = buildSkillsInstallArgs(baseUrl, skillNames);
+    commands.push({
+      command: "npx",
+      args: npxArgs,
+      manualCommand: `npx ${npxArgs.map(shellQuote5).join(" ")}`
+    });
+  }
+  return commands;
 }
 function runOneSkillsInstall(install) {
   return new Promise((resolve14) => {
@@ -28532,9 +28546,9 @@ function runOneSkillsInstall(install) {
     });
   });
 }
-async function runSkillsInstall(baseUrl, skillNames) {
+async function runSkillsInstall(installs) {
   const failures = [];
-  for (const install of resolveSkillsInstallCommands(baseUrl, skillNames)) {
+  for (const install of installs) {
     const result = await runOneSkillsInstall(install);
     if (result.ok) return true;
     failures.push(result);
@@ -28624,11 +28638,17 @@ async function syncSdkSkillsIfNeeded(baseUrl, options = {}) {
     remoteSkillNames.length > 0 ? remoteSkillNames : DEFAULT_SDK_SKILL_NAMES
   );
   if (skillNames.length === 0) return;
+  const installs = resolveSkillsInstallCommands(baseUrl, skillNames);
+  if (installs.length === 0) {
+    writeUnavailableSkillsNotice(baseUrl, update.remoteVersion, skillNames);
+    return;
+  }
   writeSdkSkillsStatusLine("Deepline skills changed; syncing agent skills...");
-  const installed = await runSkillsInstall(baseUrl, skillNames);
+  const installed = await runSkillsInstall(installs);
   if (!installed) return;
   runLegacySkillsCleanup();
   writeLocalSkillsVersion(baseUrl, update.remoteVersion);
+  clearUnavailableSkillsNotice(baseUrl);
   writeSdkSkillsStatusLine("Deepline agent skills are up to date.");
 }
 

package/dist/cli/index.mjs

@@ -610,10 +610,10 @@ var SDK_RELEASE = {
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
   // 0.1.220 deprecates SDK CLI versions below 0.1.219 and updates them
   // automatically without blocking their current command.
-  version: "0.1.235",
+  version: "0.1.237",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.235",
+    latest: "0.1.237",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.219",
     commandMinimumSupported: [
@@ -1441,6 +1441,7 @@ function createSecretRedactionContext(initialValues = []) {
 
 // ../shared_libs/play-runtime/output-size-limits.ts
 var encoder = typeof TextEncoder === "undefined" ? null : new TextEncoder();
+var LEDGER_TERMINAL_RESULT_MAX_BYTES = 768 * 1024;
 var CUSTOMER_OUTPUT_VALUE_MAX_BYTES = 1 * 1024 * 1024;
 var CUSTOMER_OUTPUT_TOTAL_MAX_BYTES = 2 * 1024 * 1024;
 var RUNTIME_RECEIPT_OUTPUT_MAX_BYTES = 10 * 1024 * 1024;
@@ -12109,6 +12110,9 @@ function getRunIdFromLiveEvent(event) {
   const packageRunId = getRunRecordFromPackage(payload)?.id;
   return typeof packageRunId === "string" && packageRunId.trim() ? packageRunId : null;
 }
+function eventConfirmsPlayRunLaunch(event) {
+  return event.type === "play.run.status" && getEventPayload(event).launchConfirmed === true;
+}
 function getStatusFromLiveEvent(event) {
   if (event.type !== "play.run.status" && event.type !== "play.run.snapshot" && event.type !== "play.run.final_status") {
     return null;
@@ -12535,70 +12539,6 @@ async function waitForPlayCompletionByStream(input2) {
     }
     return null;
   };
-  const watchViaObserveTransport = async () => {
-    const controller = new AbortController();
-    let timedOut = false;
-    const remaining = remainingWaitMs();
-    const timeout = remaining === null ? null : setTimeout(
-      () => {
-        timedOut = true;
-        controller.abort();
-      },
-      Math.max(1, remaining)
-    );
-    try {
-      for await (const event of input2.client.observeRunEvents(
-        input2.workflowId,
-        {
-          signal: controller.signal,
-          fallback: "none",
-          onNotice: input2.jsonOutput ? void 0 : (message) => input2.progress.writeLine(message)
-        }
-      )) {
-        const terminal2 = await handleLiveEvent(event);
-        if (terminal2) {
-          return terminal2;
-        }
-      }
-    } finally {
-      if (timeout) {
-        clearTimeout(timeout);
-      }
-    }
-    const terminal = await fetchTerminalStatus();
-    if (terminal) {
-      return terminal;
-    }
-    if (timedOut) {
-      assertPlayWaitNotTimedOut({ ...input2, lastPhase });
-    }
-    throw new DeeplineError(
-      `Run observation for ${input2.workflowId} ended before a terminal status.`,
-      void 0,
-      "PLAY_LIVE_STREAM_ENDED",
-      { runId: input2.workflowId, workflowId: input2.workflowId }
-    );
-  };
-  try {
-    return await watchViaObserveTransport();
-  } catch (error) {
-    if (!(error instanceof RunObserveTransportUnavailableError)) {
-      throw error;
-    }
-    if (!input2.jsonOutput) {
-      input2.progress.writeLine(
-        `[play watch] live subscription unavailable (${error.reason}); falling back to SSE tail (support window, ADR-0008)`
-      );
-    }
-    recordCliTrace({
-      phase: "cli.play_observe_transport_fallback",
-      ms: Date.now() - input2.startedAt,
-      ok: true,
-      playName: input2.playName,
-      workflowId: input2.workflowId,
-      reason: error.reason
-    });
-  }
   const streamOneWindow = async () => {
     const controller = new AbortController();
     let timedOut = false;
@@ -12731,6 +12671,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
   let launchedRevisionId = input2.request.revisionId?.trim() || null;
   let eventCount = 0;
   let firstRunIdMs = null;
+  let launchConfirmed = false;
   let lastPhase = null;
   const timeout = input2.waitTimeoutMs === null ? null : setTimeout(
     () => {
@@ -12781,6 +12722,9 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
           input2.onRunStarted?.(eventRunId);
         }
       }
+      if (eventConfirmsPlayRunLaunch(event) && eventRunId === lastKnownWorkflowId) {
+        launchConfirmed = true;
+      }
       const workflowId = lastKnownWorkflowId || "pending";
       if (workflowId !== "pending" && !emittedDashboardUrl) {
         if (!input2.jsonOutput) {
@@ -12857,6 +12801,16 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
       const finalStatus = getFinalStatusFromLiveEvent(event);
       if (finalStatus) {
         lastKnownWorkflowId ||= finalStatus.runId ?? "";
+        if (finalStatus.status === "failed" && !finalStatus.runId) {
+          return {
+            ...finalStatus,
+            runId: "pending",
+            name: input2.playName,
+            playName: input2.playName,
+            dashboardUrl,
+            ...launchedRevisionId ? { revisionId: launchedRevisionId } : {}
+          };
+        }
         const canonicalTerminal = input2.request.profile === "absurd" ? await fetchKnownTerminalStatus() : {
           ...finalStatus,
           dashboardUrl,
@@ -12888,6 +12842,34 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
         });
         return canonicalTerminal;
       }
+      if (lastKnownWorkflowId && launchConfirmed) {
+        if (timeout) {
+          clearTimeout(timeout);
+        }
+        controller.abort();
+        recordCliTrace({
+          phase: "cli.play_start_stream_handoff_to_tail",
+          ms: Date.now() - startedAt,
+          ok: true,
+          playName: input2.playName,
+          workflowId: lastKnownWorkflowId,
+          eventCount,
+          firstRunIdMs,
+          lastPhase
+        });
+        return waitForPlayCompletionByStream({
+          client: input2.client,
+          playName: input2.playName,
+          workflowId: lastKnownWorkflowId,
+          dashboardUrl,
+          jsonOutput: input2.jsonOutput,
+          emitLogs: input2.emitLogs,
+          waitTimeoutMs: input2.waitTimeoutMs,
+          startedAt,
+          state,
+          progress: input2.progress
+        });
+      }
     }
   } catch (error) {
     if (timedOut) {
@@ -14060,7 +14042,7 @@ function playRunPackageTextLedgerIncomplete(pkg) {
 }
 async function resolvePlayRunOutputStatus(input2) {
   const runId = input2.status.runId;
-  if (!runId) {
+  if (!runId || runId === "pending") {
     return input2.status;
   }
   const streamedPackage = getPlayRunPackage(input2.status);
@@ -26429,7 +26411,9 @@ function printPlayLikeToolExecuteError(toolId, tool) {
   console.error(playLikeToolExecuteErrorMessage(toolId, tool));
 }
 function registerToolsCommands(program) {
-  const tools = program.command("tools").description("Search, describe, and execute atomic provider tools.").addHelpText(
+  const tools = program.command("tools").description(
+    "Search by intent or structured filters, describe, and execute atomic provider tools."
+  ).addHelpText(
     "after",
     `
 Concepts:
@@ -26468,30 +26452,34 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  const addToolSearchCommand = (command) => command.description("Search available tools.").addHelpText(
+  const addToolSearchCommand = (command) => command.description(
+    "Search available tools by intent query or structured filters."
+  ).addHelpText(
     "after",
     `
 Notes:
   Ranked discovery for atomic provider/API operations. Results include tool ids
   that can be passed to deepline tools describe or deepline tools execute.
+  Provide a query, or omit it only when --categories and/or --search_terms is
+  supplied. Providing neither is a usage error. Both filters accept
+  comma-separated values. Use a provider name in the query; --prefix is not a
+  supported option.
   The grep alias is the same ranked retrieval surface with a more literal name
   for agents that are filtering a registry rather than choosing a workflow.
 
 Examples:
   deepline tools search email
+  deepline tools search --categories company_search --search_terms "investors,funding"
   deepline tools grep "company enrichment" --categories enrichment --json
   deepline tools search verifier --search-mode v2 --json
 `
   ).option(
     "--categories <categories>",
-    "Comma-separated categories to filter ranked search"
+    "Comma-separated categories; may be used without a query"
   ).option(
     "--search_terms <terms>",
-    "Structured search terms for ranked search"
-  ).option(
-    "--search-terms <terms>",
-    "Structured search terms for ranked search"
-  ).option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
+    "Comma-separated structured search terms; may be used without a query"
+  ).option("--search-terms <terms>", "Alias for --search_terms").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
     process.exitCode = await searchTools(query, {
       json: options.json,
       compact: options.compact,
@@ -28299,7 +28287,7 @@ import {
   readFileSync as readFileSync13,
   renameSync,
   rmSync as rmSync4,
-  unlinkSync,
+  unlinkSync as unlinkSync2,
   writeFileSync as writeFileSync15
 } from "fs";
 import { homedir as homedir11 } from "os";
@@ -28307,7 +28295,13 @@ import { dirname as dirname13, isAbsolute as isAbsolute2, join as join14, relati
 
 // src/cli/skills-sync.ts
 import { spawn as spawn3, spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync11, mkdirSync as mkdirSync9, readFileSync as readFileSync12, writeFileSync as writeFileSync14 } from "fs";
+import {
+  existsSync as existsSync11,
+  mkdirSync as mkdirSync9,
+  readFileSync as readFileSync12,
+  unlinkSync,
+  writeFileSync as writeFileSync14
+} from "fs";
 import { dirname as dirname12, join as join13 } from "path";
 
 // ../shared_libs/cli/install-commands.json
@@ -28447,6 +28441,9 @@ function sdkSkillsVersionPath(baseUrl) {
 function legacySdkSkillsVersionPath(baseUrl) {
   return join13(dirname12(sdkCliStateDirPath(baseUrl)), "sdk-skills", ".version");
 }
+function unavailableSkillsNoticePath(baseUrl) {
+  return join13(sdkCliStateDirPath(baseUrl), "skills-sync-unavailable-version");
+}
 function readSdkSkillsLocalVersion(baseUrl) {
   const pluginVersion = readPluginSkillsVersion();
   if (pluginVersion) return pluginVersion;
@@ -28464,6 +28461,29 @@ function writeLocalSkillsVersion(baseUrl, version) {
   writeFileSync14(path, `${version}
 `, "utf-8");
 }
+function writeUnavailableSkillsNotice(baseUrl, remoteVersion, skillNames) {
+  const path = unavailableSkillsNoticePath(baseUrl);
+  try {
+    if (existsSync11(path) && readFileSync12(path, "utf-8").trim() === remoteVersion) {
+      return;
+    }
+    mkdirSync9(dirname12(path), { recursive: true });
+    writeFileSync14(path, `${remoteVersion}
+`, "utf-8");
+  } catch {
+  }
+  const manualCommand = `npx ${buildSkillsInstallArgs(baseUrl, skillNames).join(" ")}`;
+  writeSdkSkillsStatusLine(
+    `Deepline agent skills are out of date, but neither \`bunx\` nor \`npx\` is available. Install Node.js/npm or Bun, then run:
+${manualCommand}`
+  );
+}
+function clearUnavailableSkillsNotice(baseUrl) {
+  try {
+    unlinkSync(unavailableSkillsNoticePath(baseUrl));
+  } catch {
+  }
+}
 function sortedUniqueSkillNames(names) {
   return [...new Set(names.map((name) => name.trim()).filter(Boolean))].sort(
     (a, b) => a.localeCompare(b)
@@ -28539,24 +28559,24 @@ function shellQuote5(arg) {
   return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
 function resolveSkillsInstallCommands(baseUrl, skillNames = DEFAULT_SDK_SKILL_NAMES) {
-  const npxArgs = buildSkillsInstallArgs(baseUrl, skillNames);
-  const npxInstall = {
-    command: "npx",
-    args: npxArgs,
-    manualCommand: `npx ${npxArgs.map(shellQuote5).join(" ")}`
-  };
+  const commands = [];
   if (hasCommand("bunx")) {
     const bunxArgs = buildBunxSkillsInstallArgs(baseUrl, skillNames);
-    return [
-      {
-        command: "bunx",
-        args: bunxArgs,
-        manualCommand: `bunx ${bunxArgs.map(shellQuote5).join(" ")}`
-      },
-      npxInstall
-    ];
+    commands.push({
+      command: "bunx",
+      args: bunxArgs,
+      manualCommand: `bunx ${bunxArgs.map(shellQuote5).join(" ")}`
+    });
   }
-  return [npxInstall];
+  if (hasCommand("npx")) {
+    const npxArgs = buildSkillsInstallArgs(baseUrl, skillNames);
+    commands.push({
+      command: "npx",
+      args: npxArgs,
+      manualCommand: `npx ${npxArgs.map(shellQuote5).join(" ")}`
+    });
+  }
+  return commands;
 }
 function runOneSkillsInstall(install) {
   return new Promise((resolve14) => {
@@ -28589,9 +28609,9 @@ function runOneSkillsInstall(install) {
     });
   });
 }
-async function runSkillsInstall(baseUrl, skillNames) {
+async function runSkillsInstall(installs) {
   const failures = [];
-  for (const install of resolveSkillsInstallCommands(baseUrl, skillNames)) {
+  for (const install of installs) {
     const result = await runOneSkillsInstall(install);
     if (result.ok) return true;
     failures.push(result);
@@ -28681,11 +28701,17 @@ async function syncSdkSkillsIfNeeded(baseUrl, options = {}) {
     remoteSkillNames.length > 0 ? remoteSkillNames : DEFAULT_SDK_SKILL_NAMES
   );
   if (skillNames.length === 0) return;
+  const installs = resolveSkillsInstallCommands(baseUrl, skillNames);
+  if (installs.length === 0) {
+    writeUnavailableSkillsNotice(baseUrl, update.remoteVersion, skillNames);
+    return;
+  }
   writeSdkSkillsStatusLine("Deepline skills changed; syncing agent skills...");
-  const installed = await runSkillsInstall(baseUrl, skillNames);
+  const installed = await runSkillsInstall(installs);
   if (!installed) return;
   runLegacySkillsCleanup();
   writeLocalSkillsVersion(baseUrl, update.remoteVersion);
+  clearUnavailableSkillsNotice(baseUrl);
   writeSdkSkillsStatusLine("Deepline agent skills are up to date.");
 }
 
@@ -28914,7 +28940,7 @@ function clearAutoUpdateFailure(plan) {
   const path = autoUpdateFailurePath(plan);
   if (!path) return;
   try {
-    unlinkSync(path);
+    unlinkSync2(path);
   } catch {
   }
 }

package/dist/index.js

@@ -424,10 +424,10 @@ var SDK_RELEASE = {
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
   // 0.1.220 deprecates SDK CLI versions below 0.1.219 and updates them
   // automatically without blocking their current command.
-  version: "0.1.235",
+  version: "0.1.237",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.235",
+    latest: "0.1.237",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.219",
     commandMinimumSupported: [
@@ -1255,6 +1255,7 @@ function createSecretRedactionContext(initialValues = []) {
 
 // ../shared_libs/play-runtime/output-size-limits.ts
 var encoder = typeof TextEncoder === "undefined" ? null : new TextEncoder();
+var LEDGER_TERMINAL_RESULT_MAX_BYTES = 768 * 1024;
 var CUSTOMER_OUTPUT_VALUE_MAX_BYTES = 1 * 1024 * 1024;
 var CUSTOMER_OUTPUT_TOTAL_MAX_BYTES = 2 * 1024 * 1024;
 var RUNTIME_RECEIPT_OUTPUT_MAX_BYTES = 10 * 1024 * 1024;

package/dist/index.mjs

@@ -354,10 +354,10 @@ var SDK_RELEASE = {
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
   // 0.1.220 deprecates SDK CLI versions below 0.1.219 and updates them
   // automatically without blocking their current command.
-  version: "0.1.235",
+  version: "0.1.237",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.235",
+    latest: "0.1.237",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.219",
     commandMinimumSupported: [
@@ -1185,6 +1185,7 @@ function createSecretRedactionContext(initialValues = []) {
 
 // ../shared_libs/play-runtime/output-size-limits.ts
 var encoder = typeof TextEncoder === "undefined" ? null : new TextEncoder();
+var LEDGER_TERMINAL_RESULT_MAX_BYTES = 768 * 1024;
 var CUSTOMER_OUTPUT_VALUE_MAX_BYTES = 1 * 1024 * 1024;
 var CUSTOMER_OUTPUT_TOTAL_MAX_BYTES = 2 * 1024 * 1024;
 var RUNTIME_RECEIPT_OUTPUT_MAX_BYTES = 10 * 1024 * 1024;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.235",
+  "version": "0.1.237",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {