deepline 0.3.89 → 0.3.90

package/dist/cli/index.mjs

@@ -163,6 +163,26 @@ import { join as join24 } from "path";
 import { tmpdir as tmpdir6 } from "os";
 import { Command as Command5 } from "commander";
 
+// src/pagination.ts
+async function* iterateCursorPages(fetchPage) {
+  let cursor = null;
+  const seen = /* @__PURE__ */ new Set();
+  for (; ; ) {
+    const page = await fetchPage(cursor);
+    if (page.hasMore) {
+      if (!page.cursor || seen.has(page.cursor)) {
+        throw new Error(
+          "Pagination reported more results without an advancing cursor"
+        );
+      }
+      seen.add(page.cursor);
+    }
+    yield page.items;
+    if (!page.hasMore) return;
+    cursor = page.cursor;
+  }
+}
+
 // src/config.ts
 import {
   existsSync,
@@ -1250,20 +1270,27 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.89",
-  updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
+  // 0.3.90 is the first deliberately versioned SDK release for API v3. Play
+  // grep hard-cuts to the single Convex full-text index; it does not retain a
+  // registry/scanner reader for any SDK/API major.
+  version: "0.3.90",
+  updateSummary: "Play grep now uses one source-only Convex full-text index. It no longer scans the registry, pages through the complete indexed match set, and rejects retired grep modes. 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
   },
   contracts: {
     api: {
       name: "sdk-http-api",
-      // API v2 is append-only. A breaking public request/response change needs
-      // v3 and an explicit v2 support-window decision, never a patch release.
-      currentMajor: 2,
-      supportedMajors: [2],
-      // Accepted only to bridge SDKs released before X-Deepline-API-Major.
+      // API v3 hard-cuts Play grep to the canonical Convex index. API v2 stays
+      // admitted for the explicit SDK support window, but it selects neither a
+      // registry scanner nor another grep reader: every accepted grep request
+      // uses the same indexed query and retired flags fail at the API boundary.
+      currentMajor: 3,
+      supportedMajors: [3, 2],
+      // The first wire id is emitted by the current SDK. Remaining ids are
+      // accepted only while the API v2 support window is open.
       legacyWireIds: [
+        "2026-09-play-grep-convex-index-hard-cutover",
         "2026-07-admin-cli-local-cutover",
         "2026-07-native-monitor-launch-hard-cutover"
       ]
@@ -2512,6 +2539,10 @@ function normalizeProductNotificationEmail(value) {
   const email = typeof value === "string" ? value.trim().toLowerCase() : "";
   return email && email.length <= 320 && PRODUCT_NOTIFICATION_EMAIL_PATTERN.test(email) ? email : null;
 }
+var DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING = {
+  mode: "rolling_limit",
+  windowMs: 36e5
+};
 
 // src/stream-reconnect.ts
 var STREAM_RECONNECT_BASE_DELAY_MS = 500;
@@ -5105,6 +5136,7 @@ var DeeplineClient = class {
     this.runs = {
       get: (runId, options2) => this.getRunStatus(runId, options2),
       list: (options2) => this.listRuns(options2),
+      listPage: (options2) => this.listRunsPage(options2),
       tail: (runId, options2) => this.tailRun(runId, options2),
       logs: (runId, options2) => this.getRunLogs(runId, options2),
       input: (runId) => this.getRunInput(runId),
@@ -6318,6 +6350,10 @@ var DeeplineClient = class {
    * ```
    */
   async listRuns(options) {
+    return (await this.listRunsPage(options)).runs;
+  }
+  /** Read one run page without discarding server pagination metadata. */
+  async listRunsPage(options) {
     const playName = options.play?.trim();
     const params = new URLSearchParams();
     if (playName) {
@@ -6348,7 +6384,7 @@ var DeeplineClient = class {
     const response = await this.http.get(
       `/api/v2/runs?${params.toString()}`
     );
-    return response.runs ?? [];
+    return { ...response, runs: response.runs ?? [] };
   }
   /**
    * Observe one run's live events. Uses the Convex Run Snapshot subscription
@@ -6743,13 +6779,33 @@ var DeeplineClient = class {
     );
   }
   /**
-   * List callable plays visible to the workspace.
+   * List one page of callable plays; grep retains exhaustive matching results.
+   * Use listPlaysPage to retain pagination metadata.
    *
    * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
    * `origin: "owned"` for org-owned plays.
    */
   async listPlays(options) {
+    if (!options?.grep?.trim()) {
+      return (await this.requestPlaysPage(options, false)).plays;
+    }
+    const plays = [];
+    for await (const items of iterateCursorPages(async (cursor) => {
+      const page = await this.listPlaysPage({ ...options, cursor });
+      return { items: page.plays, cursor: page.cursor, hasMore: page.hasMore };
+    })) {
+      plays.push(...items);
+    }
+    return plays;
+  }
+  /** Read one bounded inventory page; cursor continues the same filters. */
+  async listPlaysPage(options) {
+    return this.requestPlaysPage(options);
+  }
+  async requestPlaysPage(options, paginateInventory = true) {
     const params = new URLSearchParams();
+    if (paginateInventory && !options?.grep?.trim())
+      params.set("inventory_paginated", "1");
     if (options?.origin) params.set("origin", options.origin);
     if (options?.categories) {
       params.set(
@@ -6761,26 +6817,27 @@ var DeeplineClient = class {
       params.set("include_tool_categories", "1");
     }
     if (options?.includeArchived) params.set("include_archived", "1");
+    if (options?.includeCostEstimates) {
+      params.set("include_cost_estimates", "1");
+    }
     if (options?.grep?.trim()) {
       params.set("grep", options.grep.trim());
-      params.set("grep_mode", options.grepMode ?? "all");
-      params.set("grep_paginated", "1");
       params.set("limit", "60");
     }
-    const plays = [];
-    let cursor = null;
-    let hasMore = true;
-    do {
-      if (cursor) params.set("cursor", cursor);
-      const suffix = params.toString() ? `?${params.toString()}` : "";
-      const response = await this.http.get(
-        `/api/v2/plays${suffix}`
-      );
-      plays.push(...response.plays ?? []);
-      cursor = response.pagination?.cursor ?? response.cursor ?? null;
-      hasMore = Boolean(response.pagination?.hasMore ?? response.hasMore);
-    } while (Boolean(options?.grep?.trim()) && hasMore && cursor);
-    return plays;
+    if (options?.limit !== void 0) {
+      if (!Number.isSafeInteger(options.limit) || options.limit < 1) {
+        throw new Error("Play page limit must be a positive integer");
+      }
+      params.set("limit", String(options.limit));
+    }
+    if (options?.cursor) params.set("cursor", options.cursor);
+    const suffix = params.size ? `?${params.toString()}` : "";
+    const response = await this.http.get(`/api/v2/plays${suffix}`);
+    return {
+      plays: response.plays ?? [],
+      cursor: response.pagination?.cursor ?? response.cursor ?? null,
+      hasMore: Boolean(response.pagination?.hasMore ?? response.hasMore)
+    };
   }
   /** Set whether an org-owned Play sorts before unpinned Plays. */
   async setPlayPinned(playName, pinned) {
@@ -6914,7 +6971,7 @@ var DeeplineClient = class {
       groupKey,
       name,
       enabled: true,
-      deliveryTiming: { mode: "immediate" },
+      deliveryTiming: DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING,
       source: "workspace",
       configMode: "custom",
       version: 0
@@ -8142,13 +8199,6 @@ function getAuthedHttpClient() {
   const config = resolveConfig();
   return { config, http: new HttpClient(config) };
 }
-async function writeOutputFile(filename, content) {
-  const outputDir = resolve2(process.cwd(), "deepline", "data");
-  await mkdir(outputDir, { recursive: true });
-  const fullPath = join4(outputDir, filename);
-  await writeFile(fullPath, content, "utf-8");
-  return fullPath;
-}
 function stableOsUserId() {
   try {
     const info = userInfo();
@@ -8791,13 +8841,6 @@ function createTimestampedName(prefix, extension) {
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
   return `${prefix}-${timestamp}.${extension}`;
 }
-async function writeCsvRowsFile(prefix, rows) {
-  const path = await writeOutputFile(
-    createTimestampedName(prefix, "csv"),
-    csvStringFromRows(rows)
-  );
-  return path;
-}
 function clip(value, maxLength) {
   return value.length > maxLength ? `${value.slice(0, maxLength - 1)}\u2026` : value;
 }
@@ -9582,7 +9625,7 @@ Notes:
   workspace. To switch, use deepline org list and deepline org set <org-id>.
 `
   );
-  auth.command("workspaces").description("Deprecated. Use deepline org list to see workspaces.").action(() => {
+  auth.command("workspaces", { hidden: true }).description("Deprecated. Use deepline org list to see workspaces.").action(() => {
     console.error(
       "Workspaces live under `deepline org`.\n  List:   deepline org list\n  Switch: deepline org set <org-id>\n`deepline auth register` re-approves this device; it does not change the active workspace."
     );
@@ -9679,7 +9722,6 @@ var SUBSCRIPTION_STATUS_NEXT_COMMAND = "deepline billing subscription status --j
 var SUBSCRIPTION_CANCEL_PATH = "/api/v2/billing/subscription/cancel";
 var BILLING_TOP_UP_PATH = "/api/v2/billing/top-up";
 var DEFAULT_BALANCE_RECOVERY_CREDITS = 100;
-var BILLING_HISTORY_EXPORT_LIMIT = 5e3;
 function billingFailureFromError(error, options) {
   if (error instanceof AuthError) {
     return {
@@ -9970,6 +10012,9 @@ async function handleBalance(options) {
   );
   return;
 }
+function quoteShellArgument(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
 async function handleUsage(options) {
   const { http } = getAuthedHttpClient();
   const params = new URLSearchParams();
@@ -9986,6 +10031,7 @@ async function handleUsage(options) {
   const recent = payload.recent ?? {};
   const last30Usage = usage.last_30_days_usage_credits ?? usage.month_spent_credits;
   const temporaryHolds = Number(usage.temporary_hold_credits ?? 0);
+  const nextPage = typeof recent.next_cursor === "string" && recent.next_cursor.length > 0 ? `deepline billing usage --cursor ${quoteShellArgument(recent.next_cursor)}${options.limit ? ` --limit ${options.limit}` : ""}${options.runId ? ` --run-id ${quoteShellArgument(options.runId)}` : ""} --json` : null;
   const lines = [
     `Balance: ${payload.balance ?? "(unknown)"}`,
     `Last 30 days usage: ${last30Usage ?? "(unknown)"}`,
@@ -9997,13 +10043,20 @@ async function handleUsage(options) {
     ...recentUsageLines(
       Array.isArray(recent.entries) ? recent.entries : []
     ),
-    ...typeof recent.next_cursor === "string" && recent.next_cursor.length > 0 ? [
-      `Next page: deepline billing usage --cursor ${recent.next_cursor}${options.limit ? ` --limit ${options.limit}` : ""}${options.runId ? ` --run-id ${options.runId}` : ""}`
+    ...recent.has_more === true || recent.incomplete === true ? ["List truncated \u2014 more recent calls match this query."] : [],
+    ...nextPage ? [`Next page: ${nextPage}`] : [],
+    ...!nextPage && (recent.has_more === true || recent.incomplete === true) ? [
+      "No continuation is available for this view. Use deepline billing ledger export all --json for the full ledger."
     ] : []
   ];
   printCommandEnvelope(
     {
       ...payload,
+      recent: {
+        ...recent,
+        is_truncated: recent.has_more === true || recent.incomplete === true
+      },
+      next: { page: nextPage },
       render: { sections: [{ title: "billing usage", lines }] }
     },
     { json: options.json }
@@ -10067,6 +10120,39 @@ async function handleLimitOff(options) {
     { json: options.json }
   );
 }
+async function exportLedger(http, outputPath, options) {
+  let summary = { row_count: 0, net_delta_credits: 0 };
+  let initialized = false;
+  for await (const entries of iterateCursorPages(async (cursor) => {
+    const params = new URLSearchParams({ limit: "5000" });
+    if (cursor) params.set("cursor", cursor);
+    if (options.sinceAt !== null)
+      params.set("since_at", String(options.sinceAt));
+    if (options.runId) params.set("run_id", options.runId);
+    if (options.operation) params.set("operation", options.operation);
+    const payload = await http.get(
+      `/api/v2/billing/ledger?${params.toString()}`
+    );
+    if (!Array.isArray(payload.entries) || typeof payload.has_more !== "boolean") {
+      throw new Error("Billing ledger response is missing entries");
+    }
+    return {
+      items: payload.entries,
+      hasMore: payload.has_more === true,
+      cursor: typeof payload.next_cursor === "string" ? payload.next_cursor : null
+    };
+  })) {
+    if (!initialized) {
+      await mkdir2(dirname6(outputPath), { recursive: true });
+      await writeFile2(outputPath, ledgerRowsToCsv([], true), "utf-8");
+      initialized = true;
+    }
+    const rows = entries.map(ledgerApiEntryToRow);
+    await appendFile(outputPath, ledgerRowsToCsv(rows, false), "utf-8");
+    summary = summarizeLedgerRows(summary, rows);
+  }
+  return summary;
+}
 async function handleHistory(options) {
   const { http } = getAuthedHttpClient();
   const windows = {
@@ -10076,41 +10162,20 @@ async function handleHistory(options) {
     "1y": 31536e3
   };
   const sinceAt = Math.max(0, Math.floor(Date.now() / 1e3) - windows[options.time]) * 1e3;
-  const entries = [];
-  let cursor = null;
-  while (entries.length < BILLING_HISTORY_EXPORT_LIMIT) {
-    const params = new URLSearchParams({
-      since_at: String(sinceAt),
-      limit: String(BILLING_HISTORY_EXPORT_LIMIT - entries.length)
-    });
-    if (cursor !== null) params.set("cursor", cursor);
-    const payload = await http.get(
-      `/api/v2/billing/ledger?${params.toString()}`
-    );
-    if (Array.isArray(payload.entries)) {
-      entries.push(
-        ...payload.entries.slice(
-          0,
-          BILLING_HISTORY_EXPORT_LIMIT - entries.length
-        )
-      );
-    }
-    const nextCursor = typeof payload.next_cursor === "string" && payload.next_cursor.length > 0 ? payload.next_cursor : null;
-    if (payload.has_more !== true || nextCursor === null) break;
-    if (nextCursor === cursor) {
-      throw new Error("Billing history pagination cursor did not advance");
-    }
-    cursor = nextCursor;
-  }
-  const rows = entries.map(ledgerApiEntryToRow);
-  const outputPath = await writeCsvRowsFile(
-    `billing-history-${options.time}`,
-    rows
+  const outputPath = resolve3(
+    process.cwd(),
+    "deepline",
+    "data",
+    createTimestampedName(`billing-history-${options.time}`, "csv")
   );
+  const summary = await exportLedger(http, outputPath, { sinceAt });
   printCommandEnvelope(
     {
       output_path: outputPath,
-      row_count: rows.length,
+      row_count: summary.row_count,
+      has_more: false,
+      is_truncated: false,
+      next_cursor: null,
       time_window: options.time,
       render: {
         sections: [
@@ -10118,7 +10183,7 @@ async function handleHistory(options) {
             title: "billing history",
             lines: [
               `Billing history written to ${outputPath}`,
-              `${rows.length} row(s) exported.`
+              `${summary.row_count} row(s) exported.`
             ]
           }
         ]
@@ -10143,40 +10208,18 @@ async function handleLedgerExportAll(options) {
   }
   const { http } = getAuthedHttpClient();
   const outputPath = options.output ? resolve3(String(options.output)) : defaultLedgerExportPath();
-  let summary = { row_count: 0, net_delta_credits: 0 };
-  let cursor = null;
-  let initializedOutput = false;
-  for (; ; ) {
-    const params = new URLSearchParams({ limit: "5000" });
-    if (cursor !== null) params.set("cursor", cursor);
-    if (options.runId) params.set("run_id", options.runId);
-    if (options.operation) params.set("operation", options.operation);
-    if (sinceAt !== null) params.set("since_at", String(sinceAt));
-    const payload = await http.get(
-      `/api/v2/billing/ledger?${params.toString()}`
-    );
-    const entries = Array.isArray(payload.entries) ? payload.entries : [];
-    const rows = entries.map(ledgerApiEntryToRow);
-    if (!initializedOutput) {
-      await mkdir2(dirname6(outputPath), { recursive: true });
-      await writeFile2(outputPath, ledgerRowsToCsv([], true), "utf-8");
-      initializedOutput = true;
-    }
-    if (rows.length > 0) {
-      await appendFile(outputPath, ledgerRowsToCsv(rows, false), "utf-8");
-      summary = summarizeLedgerRows(summary, rows);
-    }
-    const nextCursor = typeof payload.next_cursor === "string" && payload.next_cursor.length > 0 ? payload.next_cursor : null;
-    if (payload.has_more !== true || nextCursor === null) {
-      break;
-    }
-    if (nextCursor === cursor) break;
-    cursor = nextCursor;
-  }
+  const summary = await exportLedger(http, outputPath, {
+    sinceAt,
+    runId: options.runId,
+    operation: options.operation
+  });
   printCommandEnvelope(
     {
       output_path: outputPath,
       row_count: summary.row_count,
+      has_more: false,
+      is_truncated: false,
+      next_cursor: null,
       net_delta_credits: summary.net_delta_credits,
       scope: "workspace",
       ...options.runId ? { run_id: options.runId } : {},
@@ -10921,7 +10964,9 @@ Examples:
     `
 Notes:
   Read-only server query that writes a local CSV file. With --json, stdout is a
-  summary containing the output path and row count.
+  summary containing the output path, row count, and completeness metadata.
+  Exports the complete window using bounded pages. For an exact start timestamp:
+  deepline billing ledger export all --since <ISO-8601> --json
 
 Examples:
   deepline billing history --time 1m
@@ -10989,7 +11034,10 @@ Examples:
       "Disable automatic recharge without clearing saved amounts."
     ).option("--idempotency-key <key>", "Stable retry key").option("--dry-run", "Print the planned update without applying it").option("--json", "Emit JSON output").action(handleAutoRechargeOff)
   );
-  billing.command("change-plan").description("Start or change the target billing plan.").argument("<plan_sku>", "payg-v1, builder-v1, growth-v1, growth-canary-v1, or team-v1").option("--idempotency-key <key>", "Stable retry key").option("--json", "Emit JSON output").action(handleTargetPlan);
+  billing.command("change-plan").description("Start or change the target billing plan.").argument(
+    "<plan_sku>",
+    "payg-v1, builder-v1, growth-v1, growth-canary-v1, or team-v1"
+  ).option("--idempotency-key <key>", "Stable retry key").option("--json", "Emit JSON output").action(handleTargetPlan);
   billing.command("cancel-plan").description("Cancel a target subscription at period end, or undo it.").option("--undo", "Undo a pending period-end cancellation").option("--idempotency-key <key>", "Stable retry key").option("--json", "Emit JSON output").action(handleTargetPlanCancellation);
   billing.command("portal").description("Open the Stripe-hosted billing recovery portal.").option("--no-open", "Print the URL without opening a browser").option("--json", "Emit JSON output").action(handleTargetPortal);
   billing.command("plans").description("Show published plans and the plan you are on.").addHelpText(
@@ -19839,6 +19887,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
             runId: workflowId,
             playName: input2.playName,
             dashboardUrl,
+            inputFieldCount: Object.keys(input2.request.input ?? {}).length,
             jsonOutput: false,
             progress: input2.progress
           });
@@ -23482,12 +23531,13 @@ async function handleRunsList(args) {
     return 1;
   }
   const client2 = new DeeplineClient();
-  const runs = (await client2.runs.list({
+  const page = await client2.runs.listPage({
     ...playName ? { play: playName } : {},
     ...statusFilter ? { status: statusFilter } : {},
     ...limit !== void 0 ? { limit } : {},
     ...offset !== void 0 ? { offset } : {}
-  })).map((run) => ({
+  });
+  const runs = page.runs.map((run) => ({
     runId: run.workflowId,
     // `workflowId` is the legacy SDK name for the same public Deepline run
     // identity. Keep it during the compatibility window, but never label the
@@ -23525,11 +23575,24 @@ async function handleRunsList(args) {
     if (run.rootRunId) lines2.push(`  root: ${run.rootRunId}`);
     return lines2.join("\n");
   });
+  const nextOffset = (page.offset ?? offset ?? 0) + runs.length;
+  const nextPage = page.hasMore && playName ? `deepline runs list --play ${shellQuote2(playName)}${statusFilter ? ` --status ${shellQuote2(statusFilter)}` : ""} --limit ${page.limit ?? limit ?? 20} --offset ${nextOffset} --json` : null;
+  if (page.hasMore) {
+    lines.push("List truncated \u2014 more runs match this filter.");
+    lines.push(
+      nextPage ? `Next page: ${nextPage}` : "Narrow with --play <play-name> to page through runs."
+    );
+  }
   printCommandEnvelope(
     {
       runs,
       count: runs.length,
+      ...page.total !== void 0 ? { total: page.total } : {},
+      offset: page.offset ?? offset ?? 0,
+      limit: page.limit ?? limit ?? (playName ? 20 : 100),
+      ...page.hasMore !== void 0 ? { has_more: page.hasMore, is_truncated: page.hasMore } : {},
       next: {
+        page: nextPage,
         get: runs[0]?.runId ? `deepline runs get ${runs[0].runId} --json` : null
       },
       render: { sections: [{ title: "runs", lines }] }
@@ -24177,23 +24240,47 @@ async function handlePlayVersions(args) {
   }
   return 0;
 }
+function formatPlayCostEstimate(estimate) {
+  if (!estimate || estimate.status === "unavailable") {
+    return `unavailable${estimate ? `: ${estimate.message}` : ""}`;
+  }
+  const formatCredits = (value) => value.toLocaleString("en-US", {
+    maximumFractionDigits: value < 1 ? 4 : 2
+  });
+  const credits = estimate.lowCredits === estimate.highCredits ? `${estimate.source === "observed" ? "~" : ""}${formatCredits(estimate.lowCredits)}` : `${formatCredits(estimate.lowCredits)}\u2013${formatCredits(estimate.highCredits)}`;
+  const unit = estimate.unit === "row" ? "output row" : "run";
+  const source = estimate.source === "observed" ? `observed from ${estimate.sampleRunCount} ${estimate.sampleRunCount === 1 ? "run" : "runs"}` : "static estimate";
+  return `${credits} Deepline credits per ${unit} (${source})`;
+}
 async function handlePlayList(args) {
   const jsonOutput = argsWantJson(args);
+  const showCost = args.includes("--show-cost");
   const client2 = new DeeplineClient();
   const categoriesIndex = args.indexOf("--categories");
   const categories = categoriesIndex >= 0 ? args[categoriesIndex + 1]?.trim() : void 0;
-  const plays = await client2.listPlays({
+  const limitIndex = args.indexOf("--limit");
+  const cursorIndex = args.indexOf("--cursor");
+  const limit = limitIndex >= 0 ? Number(args[limitIndex + 1]) : void 0;
+  const cursor = cursorIndex >= 0 ? args[cursorIndex + 1] : void 0;
+  if (limitIndex >= 0 && (!Number.isSafeInteger(limit) || limit < 1) || cursorIndex >= 0 && !cursor?.trim()) {
+    console.error("Pass a positive --limit and a non-empty --cursor.");
+    return 2;
+  }
+  const page = await client2.listPlaysPage({
     categories,
-    includeToolCategories: true
-  });
-  if (jsonOutput) {
-    process.stdout.write(`${JSON.stringify(plays)}
-`);
-    return 0;
+    includeToolCategories: true,
+    ...showCost ? { includeCostEstimates: true } : {},
+    limit,
+    cursor
+  });
+  const plays = page.plays;
+  const nextPage = page.hasMore && page.cursor ? `deepline plays list${categories ? ` --categories ${shellQuote2(categories)}` : ""}${limit ? ` --limit ${limit}` : ""}${showCost ? " --show-cost" : ""} --cursor ${shellQuote2(page.cursor)} --json` : null;
+  if (page.hasMore && !nextPage) {
+    throw new Error(
+      "Play list reported more results without a continuation cursor"
+    );
   }
-  process.stdout.write(`${plays.length} plays available:
-
-`);
+  const lines = [`${plays.length} plays in this page:`];
   for (const play of plays) {
     const flags = [
       play.pinned ? "pinned" : null,
@@ -24203,32 +24290,48 @@ async function handlePlayList(args) {
       play.isDraftDirty ? "draft-dirty" : null
     ].filter(Boolean).join(", ");
     const reference = formatPlayListReference(play);
-    process.stdout.write(`  ${reference}${flags ? ` [${flags}]` : ""}
-`);
+    lines.push(`  ${reference}${flags ? ` [${flags}]` : ""}`);
     if (play.inputSchema || play.hasInputSchema) {
-      process.stdout.write("    inputSchema: yes\n");
+      lines.push("    inputSchema: yes");
     }
     if (play.triggerStatus?.cron) {
-      process.stdout.write(
-        `    scheduled execution: ${cronExecutionLabel(play.triggerStatus.cron)}
-`
+      lines.push(
+        `    scheduled execution: ${cronExecutionLabel(play.triggerStatus.cron)}`
       );
       if (play.triggerStatus.blockedReason) {
-        process.stdout.write(
-          `    schedule issue: ${play.triggerStatus.blockedReason}
-`
-        );
+        lines.push(`    schedule issue: ${play.triggerStatus.blockedReason}`);
       }
     } else {
-      process.stdout.write("    scheduled execution: not configured\n");
+      lines.push("    scheduled execution: not configured");
     }
     if (play.triggerStatus?.webhook) {
-      process.stdout.write(`    webhook: ${play.triggerStatus.webhook}
-`);
+      lines.push(`    webhook: ${play.triggerStatus.webhook}`);
     }
-    process.stdout.write(`    run: deepline plays run ${reference} --watch
-`);
+    if (showCost) {
+      lines.push(
+        `    cost estimate: ${formatPlayCostEstimate(play.costEstimate)}`
+      );
+    }
+    lines.push(`    run: deepline plays run ${reference} --watch`);
   }
+  if (page.hasMore) {
+    lines.push("List truncated \u2014 more plays are available.");
+    lines.push(`Next page: ${nextPage}`);
+  }
+  printCommandEnvelope(
+    {
+      plays,
+      count: plays.length,
+      has_more: page.hasMore,
+      is_truncated: page.hasMore,
+      next_cursor: page.cursor,
+      next: { page: nextPage },
+      render: {
+        sections: [{ title: "plays", lines }]
+      }
+    },
+    { json: jsonOutput }
+  );
   return 0;
 }
 async function handlePlayPin(args, pinned) {
@@ -24492,76 +24595,23 @@ async function handlePlaySearch(args) {
   }
   return 0;
 }
-function normalizePlayGrepText(value) {
-  if (value === null || value === void 0) return "";
-  if (typeof value === "string") return value.toLowerCase();
-  if (typeof value === "number" || typeof value === "boolean") {
-    return String(value).toLowerCase();
-  }
-  if (Array.isArray(value)) return value.map(normalizePlayGrepText).join(" ");
-  if (typeof value === "object") {
-    return Object.values(value).map(normalizePlayGrepText).join(" ");
-  }
-  return "";
-}
-function parsePlayGrepTerms(query, mode) {
-  const trimmed = query.trim().toLowerCase();
-  if (!trimmed) return [];
-  if (mode === "phrase") return [trimmed];
-  const matches = trimmed.match(/"([^"]+)"|'([^']+)'|\S+/g) ?? [];
-  return matches.map((term) => term.replace(/^["']|["']$/g, "").trim()).filter(Boolean);
-}
-function matchesPlayGrepQuery(value, query, mode) {
-  const terms = parsePlayGrepTerms(query, mode);
-  if (terms.length === 0) return true;
-  const haystack = normalizePlayGrepText(value);
-  if (mode === "any") return terms.some((term) => haystack.includes(term));
-  return terms.every((term) => haystack.includes(term));
-}
 async function handlePlayGrep(args) {
   const query = args[0]?.trim();
   if (!query) {
-    console.error(
-      "Usage: deepline plays grep <query> [--mode all|any|phrase] [--compact] [--json]"
-    );
+    console.error("Usage: deepline plays grep <query> [--compact] [--json]");
     return 1;
   }
-  let mode = "all";
-  for (let index = 1; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--mode" && args[index + 1]) {
-      const rawMode = args[++index].trim().toLowerCase();
-      mode = rawMode === "any" || rawMode === "phrase" ? rawMode : "all";
-    }
-  }
   const compact = args.includes("--compact");
   const client2 = new DeeplineClient();
-  const plays = (await client2.listPlays({
-    grep: query,
-    grepMode: mode
-  })).filter(
-    (play) => matchesPlayGrepQuery(
-      {
-        name: play.name,
-        reference: play.reference,
-        displayName: play.displayName,
-        origin: play.origin,
-        ownerType: play.ownerType,
-        aliases: play.aliases,
-        toolCategories: play.toolCategories,
-        inputSchema: play.inputSchema,
-        outputSchema: play.outputSchema
-      },
-      query,
-      mode
-    )
-  ).map((play) => summarizePlayListItemForCli(play, { compact }));
+  const plays = (await client2.listPlays({ grep: query })).map(
+    (play) => summarizePlayListItemForCli(play, { compact })
+  );
   if (argsWantJson(args)) {
     printCompactJson({
       plays,
       count: plays.length,
       query,
-      grep: { mode, terms: parsePlayGrepTerms(query, mode) }
+      grep: { engine: "convex_full_text" }
     });
     return 0;
   }
@@ -25269,7 +25319,7 @@ Pass-through input flags:
     if (effectiveTarget && passthroughArgs[0] === effectiveTarget) {
       passthroughArgs.shift();
     }
-    process.exitCode = await handlePlayRun([
+    const exitCode = await handlePlayRun([
       ...effectiveTarget ? [effectiveTarget] : [],
       ...options.file ? ["--file", options.file] : [],
       ...options.name ? ["--name", options.name] : [],
@@ -25299,6 +25349,11 @@ Pass-through input flags:
       ...options.full ? ["--full"] : [],
       ...passthroughArgs
     ]);
+    recordCliTrace({
+      phase: "cli.play_command_exit",
+      exitCode
+    });
+    process.exitCode = exitCode;
   });
   registerPlayBootstrapCommand(play);
   play.command("get <target>").description(
@@ -25340,17 +25395,22 @@ Examples:
     `
 Notes:
   Inventory command for saved org plays and prebuilt plays. Use search for
-  ranked discovery by task or schema.
+  ranked discovery by task or schema. Returns one bounded page with has_more,
+  is_truncated, next_cursor, and a next-page command. Use --limit to choose
+  the page size and --cursor to continue with the same filters.
 
 Examples:
   deepline plays list
   deepline plays search email --json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option(
+  ).option("--limit <count>", "Page size").option("--cursor <cursor>", "Continue a previous page").option("--show-cost", "Include the per-row or per-run cost estimate").option("--json", "Emit JSON output. Also automatic when stdout is piped").option(
     "--categories <categories>",
     "Filter by comma-separated canonical tool categories"
   ).action(async (options) => {
     process.exitCode = await handlePlayList([
+      ...options.limit ? ["--limit", options.limit] : [],
+      ...options.cursor ? ["--cursor", options.cursor] : [],
+      ...options.showCost ? ["--show-cost"] : [],
       ...options.categories ? ["--categories", options.categories] : [],
       ...options.json ? ["--json"] : []
     ]);
@@ -25389,8 +25449,8 @@ Notes:
   because they are trusted, robust plays with maintained contracts. Use describe
   on a result before running it.
   Add --all only when you are specifically looking for a play you created.
-  The grep alias is the same ranked retrieval surface with a more literal name
-  for agents that are filtering the play registry.
+  Use plays grep to search active org-owned Plays through Convex's indexed
+  authored corpus. It does not search prebuilt or archived Plays.
 
 Examples:
   deepline plays search email
@@ -25408,25 +25468,24 @@ Examples:
     ]);
   });
   addPlaySearchCommand(play.command("search <query>"));
-  play.command("grep <query>").description("Literal grep over play names, schemas, and descriptions.").addHelpText(
+  play.command("grep <query>").description(
+    "Search active org-owned Plays through Convex full-text search."
+  ).addHelpText(
     "after",
     `
 Notes:
-  Literal registry filtering. Terms are matched case-insensitively against play
-  names, references, display names, ownership, and schemas. Use
-  --mode phrase for exact phrase matching, --mode any for OR, and the default
-  --mode all for AND.
+  Queries use Convex token semantics over the indexed authored Play corpus.
+  Prebuilt and archived Plays are not part of this index.
 
 Examples:
   deepline plays grep email --json
-  deepline plays grep "company contact" --mode all --json
+  deepline plays grep "company contact" --compact --json
   deepline plays describe prebuilt/company-to-contact --json
 `
-  ).option("--compact", "Emit compact schemas").option("--mode <mode>", "Grep matching mode: all, any, or phrase").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
+  ).option("--compact", "Emit compact schemas").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
     process.exitCode = await handlePlayGrep([
       query,
       ...options.compact ? ["--compact"] : [],
-      ...options.mode ? ["--mode", options.mode] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
@@ -31024,7 +31083,7 @@ async function compileConfig(input2) {
   })).config;
 }
 function registerEnrichCommand(program) {
-  program.command("enrich").allowUnknownOption(true).description("Run v1-style CSV enrichment through the V2 play runner.").configureHelp({
+  program.command("enrich", { hidden: true }).allowUnknownOption(true).description("Run v1-style CSV enrichment through the V2 play runner.").configureHelp({
     optionTerm(option) {
       return option.long === "--timeout" ? "--timeout SECONDS" : option.flags;
     }
@@ -32087,7 +32146,7 @@ function loadViewerAssets() {
         "viewer"
       )
     ] : [],
-    join12(process.cwd(), "src", "lib", "cli", "viewer")
+    join12(process.cwd(), "apps", "deepline-api", "src", "lib", "cli", "viewer")
   ];
   for (const root of candidateRoots2) {
     try {
@@ -32304,7 +32363,7 @@ function addDeprecatedSubcommand(parent, family, subcommand, description) {
   });
 }
 function registerDeprecatedCommands(program) {
-  const session = program.command("session").description("Deprecated legacy session command namespace.").allowUnknownOption(true).allowExcessArguments(true).option("--json", "Emit JSON output").argument("[args...]").addHelpText(
+  const session = program.command("session", { hidden: true }).description("Deprecated legacy session command namespace.").allowUnknownOption(true).allowExcessArguments(true).option("--json", "Emit JSON output").argument("[args...]").addHelpText(
     "after",
     `
 Notes:
@@ -32336,7 +32395,7 @@ Examples:
       `Deprecated legacy "deepline session ${subcommand}" command.`
     );
   }
-  const backend = program.command("backend").description("Deprecated legacy local backend command namespace.").allowUnknownOption(true).allowExcessArguments(true).option("--json", "Emit JSON output").argument("[args...]").addHelpText(
+  const backend = program.command("backend", { hidden: true }).description("Deprecated legacy local backend command namespace.").allowUnknownOption(true).allowExcessArguments(true).option("--json", "Emit JSON output").argument("[args...]").addHelpText(
     "after",
     `
 Notes:
@@ -34347,11 +34406,13 @@ function monitorHealthLine(health) {
   if (health.refresh?.state === "running") {
     return `refreshing whole scope \xB7 scanned ${health.scanned} so far`;
   }
+  const alignmentRequired = health.alignment_required ?? 0;
   return [
     `converged ${health.converged}/${health.scanned}`,
     `needs_repair ${health.needs_repair}`,
     `missing ${health.observed.missing}`,
     `unaudited ${health.observed.unknown + health.observed.unset}`,
+    ...alignmentRequired > 0 ? [`needs_alignment ${alignmentRequired}`] : [],
     `silent ${health.silent}`
   ].join(" \xB7 ");
 }
@@ -34385,7 +34446,9 @@ async function watchMonitorHealth(input2) {
   let last = await input2.client.monitors.health(scope);
   input2.onProgress(last);
   while (Date.now() < deadlineAt) {
-    if (last.refresh?.state !== "running" && last.needs_repair === 0 && last.observed.unknown === 0) {
+    const unresolved = last.observed.unknown + last.observed.unset;
+    const alignmentRequired = last.alignment_required ?? 0;
+    if (last.refresh?.state !== "running" && !last.truncated && last.needs_repair === 0 && (unresolved === 0 || alignmentRequired === unresolved)) {
       return last;
     }
     await new Promise(
@@ -34398,6 +34461,7 @@ async function watchMonitorHealth(input2) {
 }
 function monitorHealthText(health) {
   const partial = health.refresh?.state === "running" ? " (refreshing \u2014 counts below are not final)" : health.truncated ? " (partial \u2014 scope larger than one read)" : "";
+  const unauditedMonitors = health.unaudited_monitors ?? [];
   const lines = [
     `scope: ${health.scope.fleet_id ?? "workspace"}${partial}`,
     monitorHealthLine(health)
@@ -34420,6 +34484,29 @@ function monitorHealthText(health) {
       lines.push(`  ${entry.reason} (${entry.count})${how}`);
     }
   }
+  if (unauditedMonitors.length > 0) {
+    const reason = {
+      not_yet_audited: "has not been observed yet",
+      missing_provider_resource_id: "has no stored upstream resource id",
+      provider_observation_unknown: "the provider observation is still unknown"
+    };
+    lines.push("");
+    lines.push("unresolved monitor observations:");
+    for (const entry of unauditedMonitors) {
+      lines.push(
+        `  ${entry.monitor_key}  ${entry.tool}  \u2014 ${reason[entry.reason]}`
+      );
+    }
+  }
+  if ((health.alignment_required ?? 0) > 0) {
+    lines.push("");
+    lines.push(
+      `${health.alignment_required} monitor(s) need provider identity alignment; normal repair intentionally will not guess or create a paid replacement.`
+    );
+    lines.push(
+      `Run the exact inventory audit, then review one safe adoption candidate: deepline-admin monitors reconcile ${health.scope.org_id} --monitor <monitor-key> --environment production --json`
+    );
+  }
   if (health.worst_offenders.length > 0) {
     lines.push("");
     lines.push(
@@ -34644,9 +34731,8 @@ Exit codes:
 
 Examples:
   deepline monitors status --json
-  deepline monitors available --json          # compact list by default
-  deepline monitors available --full --json   # complete catalog
-  deepline monitors available deepline_native.company_radar --json
+  deepline tools list --categories monitors --json
+  deepline tools get deepline_native.company_radar --json
   deepline monitors check '{"key":"job-openings","tool":"deepline_native.company_radar","payload":{"domain":"stripe.com","radar_type":"company_job_openings"}}'
   deepline monitors deploy --dry-run --file monitor.json
   deepline monitors deploy --file monitor.json
@@ -34816,7 +34902,7 @@ Examples:
     )
   ).action(monitorsAction(handleMonitorsStatus));
   withJsonOption(
-    monitors.command("available [tool-id]").alias("tools").description(
+    monitors.command("available [tool-id]", { hidden: true }).alias("tools").description(
       "List the monitor types you can deploy, or describe one by tool id."
     ).addHelpText(
       "after",
@@ -34933,7 +35019,7 @@ Notes:
   Play delivery. The JSON response reports this validation scope explicitly.
   Provider-specific grammar, precedence, enum applicability, examples, and
   update semantics are returned by the live monitor contract. Inspect it with
-  \`deepline monitors available deepline_native.company_radar --json\`.
+  \`deepline tools get deepline_native.company_radar --json\`.
   For a bounded urgent Deepline Native preview, use
   controls.execution_type="priority". Deepline injects the upstream marker;
   do not author custom_fields yourself. Priority is capped at ten upstream or
@@ -34971,6 +35057,10 @@ Notes:
   no separate repair command or retry queue: rerun the same deploy/update.
   Scheduled reconciliation can also finish that exact saved cleanup; it never
   creates another monitor.
+  For TamRadar, deliberately changing payload.updates_since is an explicit
+  historical replay request, including when redeploying a disabled monitor.
+  Deepline preserves that selected boundary; filter-only deploys and ordinary
+  reactivation start from a fresh future-only source boundary instead.
   For a bounded urgent Deepline Native preview, set
   controls.execution_type="priority". Deepline injects the provider custom
   field and enforces a ten-slot per-org cap; do not use it for regular or bulk
@@ -35000,6 +35090,11 @@ positionally, via --file <path>, or from stdin with --file -.
 When <patch> includes payload, its top-level fields are merged with the stored
 payload before validation. This lets you change one filter without resending
 domain or radar_type; nested values and arrays replace atomically.
+For TamRadar, changing payload.updates_since is an explicit historical replay
+request. Deepline passes that requested boundary upstream, but previously
+delivered canonical findings are deduplicated before dispatch and billing; only
+previously unseen historical findings are chargeable. Filter-only updates,
+repair, and reactivation instead use a fresh future-only source boundary.
 Use {"controls":{"execution_type":"priority"}} only for a bounded urgent
 Deepline Native preview. The ten-radar priority cap applies on update too.
 Use {"controls":{"execution_type":null}} to release priority without
@@ -35086,7 +35181,7 @@ ${MONITOR_FLEET_HELP_EPILOG}`
 Creates a ready-to-review JSON definition. Fleets always sync ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.cadence} and retain
 a missing member for ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.removalGrace} before it is ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.onRemoved}d; those
 policies are not authored in the file. ${MONITOR_FLEET_DOCUMENTATION.stickyMembership} The payload remains the actual monitor payload for the chosen tool, so use
-\`deepline monitors available\` to discover a tool first.
+\`deepline tools list --categories monitors\` to discover a tool first.
 
 Example:
   deepline monitors fleets init account-job-openings \\
@@ -36079,7 +36174,7 @@ Examples:
     )
   ).action(handleOrgSwitch);
   addOrgSetOptions(
-    org.command("switch [selection]").description(
+    org.command("switch [selection]", { hidden: true }).description(
       "Deprecated alias for org set. Set the organization for the selected auth scope."
     ).addHelpText(
       "after",
@@ -36106,6 +36201,9 @@ Examples:
 
 // src/cli/commands/git.ts
 var GIT_DEPLOY_FEATURE = "github-deploy";
+function shellQuote3(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
 function renderProject(project) {
   const root = project.rootDirectory ? ` (${project.rootDirectory})` : "";
   const flags = [
@@ -36144,6 +36242,98 @@ async function handleList(options) {
     { json: options.json }
   );
 }
+function describeInstallationStatus(installation) {
+  switch (installation.status) {
+    case "active":
+      return [
+        `Connected to ${installation.accountLogin} (installation ${installation.installationId}).`
+      ];
+    case "uninstalled":
+      return [
+        `The Deepline GitHub App was uninstalled from ${installation.accountLogin}${installation.uninstalledAt ? ` at ${new Date(installation.uninstalledAt).toISOString()}` : ""}.`,
+        "Deploys are paused for every linked repository. Run `deepline git connect`, then `deepline git link <owner/repo>` again for each repository; links from the old installation cannot be resumed."
+      ];
+    case "suspended":
+      return [
+        `GitHub suspended the Deepline App on ${installation.accountLogin}${installation.suspendedAt ? ` at ${new Date(installation.suspendedAt).toISOString()}` : ""}.`,
+        "Pushes are not delivered while it is suspended; unsuspend it in GitHub settings."
+      ];
+  }
+}
+async function handleStatus2(options) {
+  const { http } = getAuthedHttpClient();
+  const payload = await http.get("/api/v2/github/installation");
+  const installation = payload.installation;
+  const others = (payload.installations ?? []).filter(
+    (row) => row.installationId !== installation?.installationId
+  );
+  const lines = installation ? describeInstallationStatus(installation) : [
+    "No GitHub installation is connected to this workspace. Run `deepline git connect`."
+  ];
+  for (const other of others) {
+    lines.push(
+      `Also: ${other.accountLogin} (installation ${other.installationId}) is ${other.status}.`
+    );
+  }
+  const byId = new Map(
+    (payload.installations ?? []).map((row) => [row.installationId, row])
+  );
+  const { projects } = await http.get(
+    "/api/v2/play-projects?includeDisabled=1"
+  );
+  const affected_links = projects.map((project) => {
+    const own = byId.get(project.installationId);
+    const verdict = !own ? "unknown" : own.status === "active" ? null : own.status;
+    return verdict ? {
+      id: project.id,
+      repoId: project.repoId,
+      repoFullName: project.repoFullName,
+      rootDirectory: project.rootDirectory,
+      productionBranch: project.productionBranch,
+      manifestPath: project.manifestPath,
+      checkOnPullRequest: project.checkOnPullRequest,
+      disabled: project.disabled,
+      installationId: project.installationId,
+      installationStatus: verdict
+    } : null;
+  }).filter((row) => row !== null);
+  const activeInstallations = (payload.installations ?? []).filter(
+    (row) => row.status === "active"
+  );
+  const relinkCommand = (link2) => [
+    // The numeric repo id, not the name: a repository renamed while the
+    // App was gone keeps a stale name here, and `git link` accepts the id.
+    `deepline git link ${link2.repoId}`,
+    // Stored values are admin-controlled text and this line is
+    // copy-pasted into a shell by whoever reads it, so every
+    // interpolated value below is quoted.
+    `--branch ${shellQuote3(link2.productionBranch)}`,
+    link2.rootDirectory ? `--root-dir ${shellQuote3(link2.rootDirectory)}` : "",
+    link2.manifestPath && link2.manifestPath !== "deepline.json" ? `--manifest ${shellQuote3(link2.manifestPath)}` : "",
+    link2.checkOnPullRequest ? "" : "--no-pr-checks",
+    // With several active installations no id is guessed: the reader picks.
+    activeInstallations.length > 1 ? "--installation <id>" : ""
+  ].filter(Boolean).join(" ");
+  for (const link2 of affected_links) {
+    const label = `${link2.repoFullName}${link2.rootDirectory ? ` (${link2.rootDirectory})` : ""}`;
+    lines.push(
+      link2.installationStatus !== "suspended" ? `Link again: ${label} \u2014 its installation ${link2.installationId} is ${link2.installationStatus}; run \`${relinkCommand(link2)}\`${activeInstallations.length > 1 ? ` with <id> being the installation that reaches this repo: ${activeInstallations.map((row) => `${row.installationId} (${row.accountLogin})`).join(", ")}` : ""}.` : (
+        // A link disabled during the suspension stays disabled; only an
+        // enabled one picks up again on its own when GitHub unsuspends.
+        link2.disabled ? `Paused and disabled: ${label} \u2014 its installation is suspended, and the link stays disabled after GitHub unsuspends it until you run \`deepline git set ${link2.id} --enabled\`.` : `Paused: ${label} \u2014 its installation is suspended; pushes resume when GitHub unsuspends it.`
+      )
+    );
+  }
+  printCommandEnvelope(
+    {
+      installation,
+      installations: payload.installations ?? [],
+      affected_links,
+      render: { sections: [{ title: "github installation", lines }] }
+    },
+    { json: options.json }
+  );
+}
 async function handleRepos(options) {
   const { http } = getAuthedHttpClient();
   const query = options.installation ? `?installationId=${encodeURIComponent(options.installation)}` : "";
@@ -36374,6 +36564,9 @@ Examples:
 `
   );
   git.command("connect").description("Connect a GitHub installation (browser step).").option("--json", "Emit JSON output").action(async (options) => handleConnect(options));
+  git.command("status").description(
+    "Show the workspace's GitHub installation and whether it is still usable."
+  ).option("--json", "Emit JSON output").action(async (options) => handleStatus2(options));
   git.command("repos").description("List repos the workspace's GitHub installation can reach.").option(
     "--installation <id>",
     "GitHub installation id (required when several are connected)"
@@ -36484,7 +36677,7 @@ async function handleQuickstart(options) {
   return 0;
 }
 function registerQuickstartCommands(program) {
-  program.command("quickstart").description(
+  program.command("quickstart", { hidden: true }).description(
     "Deprecated compatibility command. Use /deepline-gtm in your agent."
   ).addHelpText(
     "after",
@@ -36931,7 +37124,7 @@ import { existsSync as existsSync14, mkdirSync as mkdirSync11, readFileSync as r
 import { homedir as homedir8 } from "os";
 import { dirname as dirname15, join as join16 } from "path";
 
-// ../../shared_libs/cli/install-commands.json
+// contracts/install-commands.json
 var install_commands_default = {
   skills: {
     index_path: "/.well-known/skills/index.json",
@@ -37039,10 +37232,15 @@ function buildSkillsAddArgs(baseUrl, skillName, options = {}) {
 
 // src/cli/skills-sync.ts
 import { spawn as spawn2, spawnSync } from "child_process";
+import { randomUUID as randomUUID7 } from "crypto";
 import {
   existsSync as existsSync13,
   mkdirSync as mkdirSync10,
+  readdirSync as readdirSync4,
   readFileSync as readFileSync14,
+  renameSync,
+  rmdirSync,
+  statSync as statSync5,
   unlinkSync as unlinkSync2,
   writeFileSync as writeFileSync14
 } from "fs";
@@ -37401,6 +37599,7 @@ async function maybeReportSdkCliFailure(input2) {
 
 // src/cli/skills-sync.ts
 var CHECK_TIMEOUT_MS2 = 3e3;
+var SKILLS_SYNC_CLAIM_MAX_AGE_MS = 60 * 60 * 1e3;
 function shouldSkipSkillsSync() {
   if (detectAgentRuntime() === "claude_cowork") {
     return true;
@@ -37417,6 +37616,60 @@ function failedSkillsSyncPath(baseUrl, agents) {
     `skills-sync-failed-${agents.join("-")}-version`
   );
 }
+function inProgressSkillsSyncPath(baseUrl, agents) {
+  return join15(
+    sdkCliStateDirPath(baseUrl),
+    `skills-sync-in-progress-${agents.join("-")}`
+  );
+}
+function removeSkillsSyncClaim(path, token) {
+  try {
+    unlinkSync2(join15(path, token));
+    rmdirSync(path);
+  } catch {
+  }
+}
+function claimSkillsSync(baseUrl, agents) {
+  const path = inProgressSkillsSyncPath(baseUrl, agents);
+  try {
+    mkdirSync10(dirname14(path), { recursive: true });
+  } catch {
+    return { status: "unavailable" };
+  }
+  const token = randomUUID7();
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const pendingPath = `${path}-pending-${token}`;
+    try {
+      mkdirSync10(pendingPath);
+      writeFileSync14(join15(pendingPath, token), "", { flag: "wx" });
+      renameSync(pendingPath, path);
+      return { status: "claimed", token };
+    } catch {
+      removeSkillsSyncClaim(pendingPath, token);
+      if (!existsSync13(path)) continue;
+    }
+    if (attempt > 0) return { status: "held" };
+    try {
+      if (Date.now() - statSync5(path).mtimeMs <= SKILLS_SYNC_CLAIM_MAX_AGE_MS) {
+        return { status: "held" };
+      }
+      const owners = readdirSync4(path);
+      if (owners.length === 0) {
+        rmdirSync(path);
+        continue;
+      }
+      if (owners.length !== 1) return { status: "held" };
+      renameSync(path, `${path}-stale-${owners[0]}`);
+    } catch {
+      return { status: "held" };
+    }
+  }
+  return { status: "held" };
+}
+function clearSkillsSyncClaim(baseUrl, agents, token) {
+  const path = inProgressSkillsSyncPath(baseUrl, agents);
+  removeSkillsSyncClaim(path, token);
+}
 function hasMarkedSkillsSyncVersion(path, version) {
   return Boolean(version) && readMarkedSkillsSyncVersion(path) === version;
 }
@@ -37552,7 +37805,7 @@ function hasCommand(command) {
   });
   return result.status === 0;
 }
-function shellQuote3(arg) {
+function shellQuote4(arg) {
   return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
 function temporarySkillsSyncSkipCommand() {
@@ -37571,7 +37824,7 @@ function resolveSkillsInstallCommands(baseUrl, skillNames = DEFAULT_SDK_SKILL_NA
     commands.push({
       command: "bunx",
       args: bunxArgs,
-      manualCommand: `bunx ${bunxArgs.map(shellQuote3).join(" ")}`
+      manualCommand: `bunx ${bunxArgs.map(shellQuote4).join(" ")}`
     });
   }
   if (hasCommand("npx")) {
@@ -37579,7 +37832,7 @@ function resolveSkillsInstallCommands(baseUrl, skillNames = DEFAULT_SDK_SKILL_NA
     commands.push({
       command: "npx",
       args: npxArgs,
-      manualCommand: `npx ${npxArgs.map(shellQuote3).join(" ")}`
+      manualCommand: `npx ${npxArgs.map(shellQuote4).join(" ")}`
     });
   }
   return commands;
@@ -37746,30 +37999,43 @@ async function syncSdkSkillsIfNeeded(baseUrl, options = {}) {
     writeUnavailableSkillsNotice(baseUrl, update.remoteVersion, skillNames);
     return;
   }
-  writeSdkSkillsStatusLine("Deepline skills changed; syncing agent skills...");
-  const installResult = await runSkillsInstall(installs, agents);
-  if (!installResult.installed) {
-    const markerWritten = markFailedSkillsSync(
-      baseUrl,
-      update.remoteVersion,
-      agents
+  const claim = claimSkillsSync(baseUrl, agents);
+  if (claim.status === "held") return;
+  try {
+    if (hasFailedSkillsSync(baseUrl, update.remoteVersion, agents) || readSdkSkillsLocalVersion(baseUrl) === update.remoteVersion) {
+      return;
+    }
+    writeSdkSkillsStatusLine(
+      "Deepline skills changed; syncing agent skills..."
     );
-    void maybeReportAutomaticSkillsSyncFailure({
-      baseUrl,
-      remoteSkillsVersion: update.remoteVersion,
-      agents,
-      skillsPackage: SKILLS_NPX_PACKAGE,
-      targetSkillCount: skillNames.length,
-      markerWritten,
-      attempts: installResult.attempts
-    });
-    return;
+    const installResult = await runSkillsInstall(installs, agents);
+    if (!installResult.installed) {
+      const markerWritten = markFailedSkillsSync(
+        baseUrl,
+        update.remoteVersion,
+        agents
+      );
+      void maybeReportAutomaticSkillsSyncFailure({
+        baseUrl,
+        remoteSkillsVersion: update.remoteVersion,
+        agents,
+        skillsPackage: SKILLS_NPX_PACKAGE,
+        targetSkillCount: skillNames.length,
+        markerWritten,
+        attempts: installResult.attempts
+      });
+      return;
+    }
+    runLegacySkillsCleanup(agents);
+    writeSdkSkillsLocalVersion(baseUrl, update.remoteVersion, agents);
+    clearUnavailableSkillsNotice(baseUrl);
+    clearFailedSkillsSync(baseUrl, agents);
+    writeSdkSkillsStatusLine("Deepline agent skills are up to date.");
+  } finally {
+    if (claim.status === "claimed") {
+      clearSkillsSyncClaim(baseUrl, agents, claim.token);
+    }
   }
-  runLegacySkillsCleanup(agents);
-  writeSdkSkillsLocalVersion(baseUrl, update.remoteVersion, agents);
-  clearUnavailableSkillsNotice(baseUrl);
-  clearFailedSkillsSync(baseUrl, agents);
-  writeSdkSkillsStatusLine("Deepline agent skills are up to date.");
 }
 
 // src/cli/commands/skills.ts
@@ -39086,7 +39352,7 @@ import {
   existsSync as existsSync16,
   mkdirSync as mkdirSync13,
   readFileSync as readFileSync17,
-  renameSync,
+  renameSync as renameSync2,
   rmSync as rmSync5,
   writeFileSync as writeFileSync17
 } from "fs";
@@ -39155,7 +39421,7 @@ function writeCliUpdatePreferences(preferences, homeDir2 = homedir10()) {
       encoding: "utf8",
       mode: 384
     });
-    renameSync(tempPath, path);
+    renameSync2(tempPath, path);
   } finally {
     rmSync5(tempPath, { force: true });
   }
@@ -39212,7 +39478,7 @@ import {
   mkdirSync as mkdirSync14,
   realpathSync as realpathSync5,
   readFileSync as readFileSync19,
-  renameSync as renameSync2,
+  renameSync as renameSync3,
   rmSync as rmSync6,
   unlinkSync as unlinkSync3,
   writeFileSync as writeFileSync18
@@ -39229,7 +39495,7 @@ import {
 
 // src/cli/install-integrity.ts
 import { createRequire } from "module";
-import { existsSync as existsSync17, readFileSync as readFileSync18, statSync as statSync5 } from "fs";
+import { existsSync as existsSync17, readFileSync as readFileSync18, statSync as statSync6 } from "fs";
 import { isAbsolute as isAbsolute6, join as join19, relative as relative6, resolve as resolve17 } from "path";
 var SDK_SIDECAR_CRITICAL_PACKAGE_FILES = [
   "dist/cli/index.mjs",
@@ -39269,7 +39535,7 @@ function parseJson(path) {
 }
 function isFile(path) {
   try {
-    return statSync5(path).isFile();
+    return statSync6(path).isFile();
   } catch {
     return false;
   }
@@ -39416,14 +39682,14 @@ function posixShellQuote(value) {
 function windowsCmdQuote(value) {
   return `"${value.replace(/"/g, '""')}"`;
 }
-function shellQuote4(value) {
+function shellQuote5(value) {
   if (process.platform === "win32") {
     return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : windowsCmdQuote(value);
   }
   return posixShellQuote(value);
 }
 function buildSourceUpdateCommand(sourceRoot) {
-  const quotedRoot = shellQuote4(sourceRoot);
+  const quotedRoot = shellQuote5(sourceRoot);
   const cdCommand = process.platform === "win32" ? `cd /d ${quotedRoot}` : `cd ${quotedRoot}`;
   return `${cdCommand} && git fetch origin main --tags && git merge --ff-only origin/main`;
 }
@@ -39435,7 +39701,7 @@ function buildSidecarProjectConfigCommand(versionDir, nodeBin) {
     "fs.mkdirSync(dir,{recursive:true});",
     `fs.writeFileSync(path.join(dir,'package.json'),${JSON.stringify(NPM_SDK_SIDECAR_PACKAGE_JSON)});`
   ].join("");
-  return `${shellQuote4(nodeBin)} -e ${shellQuote4(script)} ${shellQuote4(versionDir)}`;
+  return `${shellQuote5(nodeBin)} -e ${shellQuote5(script)} ${shellQuote5(versionDir)}`;
 }
 function sidecarStateDir(input2) {
   const scope = input2.env.DEEPLINE_CONFIG_SCOPE?.trim();
@@ -39498,7 +39764,7 @@ function resolvePythonSidecarUpdatePlan(options) {
   const npmCommand = "npm";
   const registryUrl = sidecarRegistryUrl(hostUrl);
   const versionDir = join20(stateDir, "versions", "<version>");
-  const manualCommand = `${buildSidecarProjectConfigCommand(versionDir, nodeBin)} && ${npmCommand} install --prefix ${shellQuote4(versionDir)} --registry ${shellQuote4(registryUrl)} ${NPM_SDK_INSTALL_COMMON_FLAGS.map(shellQuote4).join(" ")} ${shellQuote4(packageSpec)}`;
+  const manualCommand = `${buildSidecarProjectConfigCommand(versionDir, nodeBin)} && ${npmCommand} install --prefix ${shellQuote5(versionDir)} --registry ${shellQuote5(registryUrl)} ${NPM_SDK_INSTALL_COMMON_FLAGS.map(shellQuote5).join(" ")} ${shellQuote5(packageSpec)}`;
   return {
     kind: "python-sidecar",
     stateDir,
@@ -39645,7 +39911,7 @@ function resolveUpdatePlan(options = {}) {
     args,
     ...installPrefix ? { installPrefix } : {},
     ...fallbackRegistryUrl ? { fallbackRegistryUrl } : {},
-    manualCommand: `${command} ${args.map(shellQuote4).join(" ")}`
+    manualCommand: `${command} ${args.map(shellQuote5).join(" ")}`
   };
 }
 var AUTO_UPDATE_FAILURE_FILE = ".auto-update-failure.json";
@@ -39913,23 +40179,23 @@ function writeSidecarLauncher(input2) {
     input2.path,
     [
       "#!/usr/bin/env sh",
-      `export DEEPLINE_HOST_URL=${shellQuote4(input2.hostUrl)}`,
-      `export DEEPLINE_CONFIG_SCOPE=${shellQuote4(input2.scope)}`,
-      `if ${criticalPaths.map((path) => `[ ! -f ${shellQuote4(path)} ]`).join(" || ")}; then`,
+      `export DEEPLINE_HOST_URL=${shellQuote5(input2.hostUrl)}`,
+      `export DEEPLINE_CONFIG_SCOPE=${shellQuote5(input2.scope)}`,
+      `if ${criticalPaths.map((path) => `[ ! -f ${shellQuote5(path)} ]`).join(" || ")}; then`,
       '  if [ -n "${DEEPLINE_REAL_BINARY:-}" ] && [ -x "$DEEPLINE_REAL_BINARY" ]; then',
       '    exec "$DEEPLINE_REAL_BINARY" --version=v2 "$@"',
       "  fi",
       '  printf "%s\\n" "Deepline SDK CLI install is incomplete. Run \\`deepline update\\` to repair it." >&2',
       "  exit 1",
       "fi",
-      `if ! ${shellQuote4(input2.nodeBin)} -e ${shellQuote4(esbuildProbe)} ${shellQuote4(versionDir)} >/dev/null 2>&1; then`,
+      `if ! ${shellQuote5(input2.nodeBin)} -e ${shellQuote5(esbuildProbe)} ${shellQuote5(versionDir)} >/dev/null 2>&1; then`,
       '  if [ -n "${DEEPLINE_REAL_BINARY:-}" ] && [ -x "$DEEPLINE_REAL_BINARY" ]; then',
       '    exec "$DEEPLINE_REAL_BINARY" --version=v2 "$@"',
       "  fi",
       '  printf "%s\\n" "Deepline SDK CLI install is incomplete. Run \\`deepline update\\` to repair it." >&2',
       "  exit 1",
       "fi",
-      `exec ${shellQuote4(input2.nodeBin)} ${shellQuote4(input2.entryPath)} "$@"`,
+      `exec ${shellQuote5(input2.nodeBin)} ${shellQuote5(input2.entryPath)} "$@"`,
       ""
     ].join("\n"),
     { encoding: "utf8", mode: 493 }
@@ -39997,7 +40263,7 @@ async function runPythonSidecarUpdatePlan(plan) {
         `.backup-${installedVersion}-${process.pid}-${Date.now()}`
       );
       try {
-        renameSync2(finalDir, backupDir);
+        renameSync3(finalDir, backupDir);
       } catch (error) {
         const concurrentlyPublishedFailure = sidecarInstallFailure(finalDir);
         if (!concurrentlyPublishedFailure) {
@@ -40016,7 +40282,7 @@ async function runPythonSidecarUpdatePlan(plan) {
     }
     if (shouldPublishTemp) {
       try {
-        renameSync2(tempDir, finalDir);
+        renameSync3(tempDir, finalDir);
       } catch (error) {
         rmSync6(tempDir, { recursive: true, force: true });
         const concurrentlyPublishedFailure = sidecarInstallFailure(finalDir);
@@ -40027,7 +40293,7 @@ async function runPythonSidecarUpdatePlan(plan) {
           let restoreFailure = "";
           if (backupDir && existsSync18(backupDir) && !existsSync18(finalDir)) {
             try {
-              renameSync2(backupDir, finalDir);
+              renameSync3(backupDir, finalDir);
               backupDir = null;
             } catch (restoreError) {
               restoreFailure = `; failed to restore previous install: ${restoreError.message}`;
@@ -40047,7 +40313,7 @@ async function runPythonSidecarUpdatePlan(plan) {
     if (backupDir && existsSync18(backupDir)) {
       rmSync6(finalDir, { recursive: true, force: true });
       try {
-        renameSync2(backupDir, finalDir);
+        renameSync3(backupDir, finalDir);
         backupDir = null;
       } catch {
       }
@@ -43199,9 +43465,9 @@ function apifySyncRecoveryNext(rawResponse) {
   const getDatasetItemsTool = stringField2(getDatasetItems, "tool");
   const getDatasetItemsPayload = recordField2(getDatasetItems, "payload");
   return {
-    getActorRun: `deepline tools execute ${getActorRunTool} --input ${shellQuote5(JSON.stringify(getActorRunPayload))} --json`,
+    getActorRun: `deepline tools execute ${getActorRunTool} --input ${shellQuote6(JSON.stringify(getActorRunPayload))} --json`,
     ...getDatasetItemsTool && Object.keys(getDatasetItemsPayload).length > 0 ? {
-      getDatasetItems: `deepline tools execute ${getDatasetItemsTool} --input ${shellQuote5(JSON.stringify(getDatasetItemsPayload))} --json`
+      getDatasetItems: `deepline tools execute ${getDatasetItemsTool} --input ${shellQuote6(JSON.stringify(getDatasetItemsPayload))} --json`
     } : {}
   };
 }
@@ -43374,7 +43640,7 @@ function parseExecuteOptions(args) {
 function safeFileStem(value) {
   return value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "tool";
 }
-function shellQuote5(value) {
+function shellQuote6(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function powerShellQuote(value) {
@@ -43444,7 +43710,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
     path: scriptPath,
     sourceCode: script,
     projectDir,
-    macCopyCommand: `mkdir -p ${shellQuote5(projectDir)} && cp ${shellQuote5(scriptPath)} ${shellQuote5(`${projectDir}/${fileName}`)}`,
+    macCopyCommand: `mkdir -p ${shellQuote6(projectDir)} && cp ${shellQuote6(scriptPath)} ${shellQuote6(`${projectDir}/${fileName}`)}`,
     windowsCopyCommand: `New-Item -ItemType Directory -Force -Path ${powerShellQuote(projectDir.replace(/\//g, "\\"))} | Out-Null; Copy-Item -LiteralPath ${powerShellQuote(scriptPath)} -Destination ${powerShellQuote(`${projectDir.replace(/\//g, "\\")}\\${fileName}`)}`
   };
 }
@@ -43471,7 +43737,7 @@ function buildToolExecuteBaseEnvelope(input2) {
     envelope,
     "output"
   );
-  const inspectCommand = `deepline tools execute ${input2.toolId} --input ${shellQuote5(JSON.stringify(input2.params))} --json`;
+  const inspectCommand = `deepline tools execute ${input2.toolId} --input ${shellQuote6(JSON.stringify(input2.params))} --json`;
   const actions = input2.listConversion ? [
     {
       label: "next",
@@ -44291,7 +44557,7 @@ async function handleTail(id, runId, options) {
   }
 }
 function registerWorkflowCommands(program) {
-  const workflows = program.command("workflows").description(
+  const workflows = program.command("workflows", { hidden: true }).description(
     "Legacy cloud workflows (now becoming plays). Commands still work; use `workflows transform` to migrate one to a play. " + TRIGGER_REDIRECT
   ).addHelpText(
     "after",
@@ -45111,4 +45377,10 @@ Examples:
   }
   process.exitCode = process.exitCode ?? 0;
 }
-main();
+var DEV_CLI_AWAIT_MAIN = Symbol.for("@deepline/sdk/dev-cli-await-main");
+if (globalThis[DEV_CLI_AWAIT_MAIN] !== true) {
+  void main();
+}
+export {
+  main
+};