deepline 0.1.185 → 0.1.187

package/dist/cli/index.mjs

@@ -608,10 +608,10 @@ var SDK_RELEASE = {
   // 0.1.154 removes the short-lived generated enrich StepOptions recompute
   // fields shipped in 0.1.153.
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
-  version: "0.1.185",
+  version: "0.1.187",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.185",
+    latest: "0.1.187",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -8305,13 +8305,155 @@ var PLAY_BOOTSTRAP_STAGE_NAMES = [
   "email",
   "phone"
 ];
+var MONITOR_BOOTSTRAP_TEMPLATE = "monitor-triggered";
+var MONITOR_BOOTSTRAP_DEFAULT_TOOL = "instantly.campaign_events";
+var MONITOR_BOOTSTRAP_DEFAULT_STREAM = "webhook_events";
+function isMonitorBootstrapTemplate(value) {
+  return value === MONITOR_BOOTSTRAP_TEMPLATE;
+}
+function hasMonitorBootstrapForbiddenChar(value) {
+  for (const char of value) {
+    const code = char.codePointAt(0) ?? 0;
+    if (code < 32 || code === 127) return true;
+    if (char === "'" || char === '"' || char === "`" || char === "\\") {
+      return true;
+    }
+  }
+  return false;
+}
+function validateMonitorBootstrapFlagValue(flag, value) {
+  if (hasMonitorBootstrapForbiddenChar(value)) {
+    throw new PlayBootstrapUsageError(
+      `${flag} may not contain line breaks, control characters, quotes, or backticks. It is interpolated into the generated play source (including comments); use a plain monitor tool id / stream key / name.`
+    );
+  }
+  return value;
+}
+function parseMonitorBootstrapOptions(args) {
+  const [, ...rest] = args;
+  const options = {
+    name: MONITOR_BOOTSTRAP_TEMPLATE,
+    tool: MONITOR_BOOTSTRAP_DEFAULT_TOOL,
+    stream: MONITOR_BOOTSTRAP_DEFAULT_STREAM,
+    out: null
+  };
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    const value = () => nextFlagValue(rest, index, arg);
+    switch (arg) {
+      case "--name":
+        options.name = validateMonitorBootstrapFlagValue("--name", value());
+        index += 1;
+        break;
+      case "--tool":
+        options.tool = validateMonitorBootstrapFlagValue("--tool", value());
+        index += 1;
+        break;
+      case "--stream":
+        options.stream = validateMonitorBootstrapFlagValue("--stream", value());
+        index += 1;
+        break;
+      case "--out":
+        options.out = value();
+        index += 1;
+        break;
+      default:
+        throw new PlayBootstrapUsageError(
+          `Unknown plays bootstrap option for ${MONITOR_BOOTSTRAP_TEMPLATE}: ${arg}
+Usage: deepline plays bootstrap ${MONITOR_BOOTSTRAP_TEMPLATE} [--tool <monitor-tool-id>] [--stream <stream-key>] [--name NAME] [--out monitor.play.ts]`
+        );
+    }
+  }
+  if (!options.tool) {
+    throw new PlayBootstrapUsageError(
+      `${MONITOR_BOOTSTRAP_TEMPLATE} needs a non-empty --tool.`
+    );
+  }
+  if (!options.stream) {
+    throw new PlayBootstrapUsageError(
+      `${MONITOR_BOOTSTRAP_TEMPLATE} needs a non-empty --stream.`
+    );
+  }
+  return options;
+}
+function generateMonitorTriggeredPlaySource(options) {
+  return `import { definePlay } from 'deepline';
+import type { SqlListenerEvent } from 'deepline';
+
+// Row shape delivered by ${options.tool} / ${options.stream}. This is a starting
+// point only: inspect the real columns with
+//   deepline monitors available ${options.tool}
+// and tighten this type to the fields you read below.
+//
+// Before deploying a NEW monitor, run \`deepline monitors list\` \u2014 if one
+// already feeds this stream for your scope, this play will already react to its
+// rows (a play binds to the shared stream), so you may not need to deploy at all.
+type MonitorRow = Record<string, unknown>;
+
+export default definePlay(
+  ${jsString(options.name)},
+  async (ctx, event: SqlListenerEvent<MonitorRow>) => {
+    // The monitor delivers the changed row as event.after. It is null for
+    // DELETE operations, so guard before reading fields.
+    const row = event.after;
+    if (!row) {
+      ctx.log(\`Monitor \${event.tool}/\${event.stream} \${event.operation} with no row; nothing to do.\`);
+      return { handled: false, operation: event.operation };
+    }
+
+    ctx.log(
+      \`Monitor \${event.tool}/\${event.stream} \${event.operation}: \${JSON.stringify(row).slice(0, 200)}\`,
+    );
+
+    // Capture the changed row into a durable dataset so the run has inspectable,
+    // exportable output. ctx.dataset is a CALLABLE: ctx.dataset(key, rows) where
+    // key is a compile-time string LITERAL and rows is an array of row objects.
+    // It returns a builder; add per-row columns with .withColumn(name, resolver)
+    // and finish with .run(). There is no .push/.add \u2014 pass all rows up front.
+    // TODO: replace this plain persist with your real per-row work \u2014 enrich each
+    // row via .withColumn('...', (row, rowCtx) => rowCtx.tools.execute(...)),
+    // notify, write to another table, or fan out with rowCtx.runPlay.
+    const captured = await ctx.dataset('monitor_events', [row]).run({
+      description: \`Captured \${event.tool}/\${event.stream} \${event.operation} rows.\`,
+    });
+
+    return {
+      handled: true,
+      tool: event.tool,
+      stream: event.stream,
+      operation: event.operation,
+      changedAt: event.changedAt,
+      capturedRows: await captured.count(),
+    };
+  },
+  {
+    description: ${jsString(`Run whenever ${options.tool} writes a new ${options.stream} row.`)},
+    // A monitor trigger: this play wakes on row changes written by the bound
+    // monitor tool + stream. Discover a tool's streams and columns with:
+    //   deepline monitors available ${options.tool}
+    // To bind a different monitor, swap tool/stream (and re-check operations)
+    // for one of its (tool, stream) pairs.
+    sqlListeners: [
+      {
+        id: 'events',
+        tool: ${jsString(options.tool)},
+        stream: ${jsString(options.stream)},
+        operations: ['INSERT'],
+        // Optional: only wake on some rows \u2014 add a where filter to the binding above:
+        //   where: { after: { <column>: { eq: 'value' } } }  // operators: eq, neq, in, notIn, isNull, isNotNull, ilike
+      },
+    ],
+  },
+);
+`;
+}
 function playBootstrapUsageLine() {
   return `Usage: deepline plays bootstrap <${formatPlayBootstrapTemplates()}> --from <csv:PATH|play:REF|provider:ID|providers:ID,ID> [--using <play:REF|providers:ID,ID>] [--people play:REF] [--email <play:REF|providers:ID,ID>] [--phone <play:REF|providers:ID,ID>] [--limit 5] [--out flow.play.ts]`;
 }
 function requireBootstrapTemplate(rawTemplate) {
   if (!rawTemplate) {
     throw new PlayBootstrapUsageError(
-      `plays bootstrap needs a route template: ${formatPlayBootstrapTemplates()}.
+      `plays bootstrap needs a route template: ${formatPlayBootstrapTemplates()}|${MONITOR_BOOTSTRAP_TEMPLATE}.
 Example: deepline plays bootstrap people-email --from csv:data/leads.csv --using play:prebuilt/name-and-domain-to-email-waterfall --out email-flow.play.ts`
     );
   }
@@ -8319,7 +8461,7 @@ Example: deepline plays bootstrap people-email --from csv:data/leads.csv --using
     const looksLikePlayReference = rawTemplate.includes("/") || rawTemplate.endsWith(".play.ts");
     throw new PlayBootstrapUsageError(
       `Unknown plays bootstrap template: ${rawTemplate}
-Supported templates: ${formatPlayBootstrapTemplates()}` + (looksLikePlayReference ? `
+Supported templates: ${formatPlayBootstrapTemplates()}|${MONITOR_BOOTSTRAP_TEMPLATE}` + (looksLikePlayReference ? `
 
 "${rawTemplate}" looks like an existing play reference or file, not a bootstrap template. Do not run plays bootstrap on prebuilt/<play-name>. Use "deepline plays run ${rawTemplate} --input '{...}' --watch" to run it directly, "deepline plays describe ${rawTemplate} --json" to inspect its contract, or "deepline plays get ${rawTemplate} --source --out scratchpad.play.ts" to clone/edit it.` : "")
     );
@@ -9528,7 +9670,25 @@ function renderPlayBootstrapError(error) {
   console.error(errorMessage2(error));
   return error instanceof PlayBootstrapError ? error.exitCode : 1;
 }
+function writeBootstrapSource(source, out) {
+  if (out) {
+    writeFileSync8(resolve7(out), source, "utf-8");
+    process.stdout.write(`Wrote ${resolve7(out)}
+`);
+    return 0;
+  }
+  process.stdout.write(source);
+  return 0;
+}
+function runMonitorBootstrap(args) {
+  const options = parseMonitorBootstrapOptions(args);
+  const source = generateMonitorTriggeredPlaySource(options);
+  return writeBootstrapSource(source, options.out);
+}
 async function runPlayBootstrap(args) {
+  if (isMonitorBootstrapTemplate(args[0])) {
+    return runMonitorBootstrap(args);
+  }
   const options = parsePlayBootstrapOptions(args);
   const client2 = new DeeplineClient();
   const contracts = await loadBootstrapContracts(client2, options);
@@ -9538,20 +9698,15 @@ async function runPlayBootstrap(args) {
     ...contracts,
     ...csvContext
   });
-  if (options.out) {
-    writeFileSync8(resolve7(options.out), source, "utf-8");
-    process.stdout.write(`Wrote ${resolve7(options.out)}
-`);
-    return 0;
-  }
-  process.stdout.write(source);
-  return 0;
+  return writeBootstrapSource(source, options.out);
 }
 async function handlePlayBootstrap(args) {
   return runPlayBootstrap(args).catch(renderPlayBootstrapError);
 }
 function registerPlayBootstrapCommand(play) {
-  play.command("bootstrap <template>").description("Print a scratchpad play for a GTM route template.").addHelpText(
+  play.command("bootstrap <template>").description(
+    "Print a scratchpad play for a GTM route or monitor-triggered template."
+  ).addHelpText(
     "after",
     `
 Notes:
@@ -9575,6 +9730,13 @@ Notes:
     company-people          company/account rows -> people play
     company-people-email    company/account rows -> people play -> email finder
     company-people-phone    company/account rows -> people play -> phone finder
+    monitor-triggered       run a play whenever a monitor writes a new row
+                            (definePlay with sqlListeners; no --from/stage flags)
+
+  Monitor-triggered options (only for the monitor-triggered template):
+    --tool <monitor-tool-id>   monitor tool to bind (default instantly.campaign_events)
+    --stream <stream-key>      output stream to listen on (default webhook_events)
+    Discover a tool's streams/columns with: deepline monitors available <id>
 
   Resource refs:
     csv:./contacts.csv
@@ -9604,6 +9766,9 @@ Examples:
   deepline plays bootstrap people-email --from provider:dropleads_search_people --using providers:hunter_email_finder,leadmagic_email_finder --limit 5 --out prospecting.play.ts
   deepline plays bootstrap company-people-email --from provider:crustdata_companydb_search --people play:prebuilt/company-to-contact --email play:prebuilt/name-and-domain-to-email-waterfall --limit 5 --out account-contacts.play.ts
   deepline plays bootstrap company-list --from provider:crustdata_companydb_search --limit 5 --out companies.play.ts
+
+  deepline plays bootstrap monitor-triggered --out on-new-row.play.ts
+  deepline plays bootstrap monitor-triggered --tool tamradar.company_radar --stream company_job_openings --out on-new-job.play.ts
 `
   ).option("--name <name>", "Generated play name").option(
     "--from <ref>",
@@ -9620,7 +9785,13 @@ Examples:
   ).option(
     "--phone <ref>",
     "Phone finder stage: play:REF, provider:ID, or providers:ID,ID"
-  ).option("--limit <n>", "Maximum rows to fan out in the generated play").option("--out <path>", "Write generated play source to a file").action(async (template, options) => {
+  ).option("--limit <n>", "Maximum rows to fan out in the generated play").option(
+    "--tool <id>",
+    "monitor-triggered only: monitor tool id to bind (e.g. instantly.campaign_events)"
+  ).option(
+    "--stream <key>",
+    "monitor-triggered only: monitor output stream to listen on (e.g. webhook_events)"
+  ).option("--out <path>", "Write generated play source to a file").action(async (template, options) => {
     process.exitCode = await handlePlayBootstrap([
       template,
       ...options.name ? ["--name", options.name] : [],
@@ -9630,6 +9801,8 @@ Examples:
       ...options.email ? ["--email", options.email] : [],
       ...options.phone ? ["--phone", options.phone] : [],
       ...options.limit ? ["--limit", options.limit] : [],
+      ...options.tool ? ["--tool", options.tool] : [],
+      ...options.stream ? ["--stream", options.stream] : [],
       ...options.out ? ["--out", options.out] : []
     ]);
   });
@@ -13554,6 +13727,89 @@ function printToolGetterHints(hints) {
     if (hint.unavailable) console.log(`      - warning: ${hint.unavailable}`);
   }
 }
+function printPlayTriggers(triggers) {
+  if (!triggers) return;
+  const hasAny = (triggers.sqlListeners?.length ?? 0) > 0 || Boolean(triggers.cron) || triggers.webhook === true;
+  if (!hasAny) return;
+  console.log("  triggers:");
+  for (const listener of triggers.sqlListeners ?? []) {
+    const target = listener.tool && listener.stream ? `${listener.tool}/${listener.stream}` : listener.tool ?? listener.stream ?? listener.id;
+    const operations = listener.operations.length ? listener.operations.join(", ") : "INSERT, UPDATE";
+    const whereNote = listener.where ? " (with where filter)" : "";
+    console.log(`    sqlListeners \u2192 ${target} on ${operations}${whereNote}`);
+  }
+  if (triggers.cron) {
+    const timezone = triggers.cron.timezone ? ` (${triggers.cron.timezone})` : "";
+    console.log(`    cron \u2192 ${triggers.cron.schedule}${timezone}`);
+  }
+  if (triggers.webhook === true) {
+    console.log("    webhook \u2192 enabled");
+  }
+}
+function printRecognizedSummary(recognized) {
+  if (!recognized) return;
+  if (recognized.tools?.length) {
+    console.log(`  tools: ${recognized.tools.join(", ")}`);
+  }
+  for (const dataset of recognized.datasets ?? []) {
+    const columns = dataset.columns?.length ? ` (${dataset.columns.length} col${dataset.columns.length === 1 ? "" : "s"}: ${dataset.columns.join(", ")})` : "";
+    console.log(`  dataset ${dataset.name}${columns}`);
+  }
+  if (recognized.inputs?.length) {
+    console.log(`  inputs: ${recognized.inputs.join(", ")}`);
+  }
+  if (recognized.outputs?.length) {
+    console.log(`  outputs: ${recognized.outputs.join(", ")}`);
+  }
+}
+function formatPlayCheckIssueLines(issue) {
+  const lines = [`  - ${issue.message}`];
+  if (issue.path) {
+    lines.push(`      at ${issue.path}`);
+  }
+  if (issue.validOptions?.length) {
+    lines.push(`      \u2192 valid: [${issue.validOptions.join(", ")}]`);
+  }
+  if (issue.hint?.trim()) {
+    lines.push(`      hint: ${issue.hint.trim()}`);
+  }
+  if (issue.docsHint?.trim()) {
+    lines.push(`      next: ${issue.docsHint.trim()}`);
+  }
+  return lines;
+}
+function printPlayCheckIssues(issues, writer) {
+  if (!issues?.length) return;
+  const errorIssues = issues.filter((issue) => issue.severity === "error");
+  const warningIssues = issues.filter((issue) => issue.severity === "warning");
+  if (errorIssues.length) {
+    writer("  issues:");
+    for (const issue of errorIssues) {
+      for (const line of formatPlayCheckIssueLines(issue)) writer(line);
+    }
+  }
+  if (warningIssues.length) {
+    writer("  warnings:");
+    for (const issue of warningIssues) {
+      for (const line of formatPlayCheckIssueLines(issue)) writer(line);
+    }
+  }
+}
+function partitionMirroredErrors(errors, issues) {
+  const errorMessages = (issues ?? []).filter((issue) => issue.severity === "error").map((issue) => issue.message.trim()).filter((message) => message.length > 0);
+  if (errorMessages.length === 0) {
+    return { unstructuredErrors: errors ?? [] };
+  }
+  const isMirror = (error) => {
+    const trimmed = error.trim();
+    return errorMessages.some(
+      (message) => trimmed === message || trimmed.startsWith(message)
+    );
+  };
+  return {
+    unstructuredErrors: (errors ?? []).filter((error) => !isMirror(error))
+  };
+}
 async function handlePlayCheck(args) {
   const options = parsePlayCheckOptions(args);
   if (!isFileTarget(options.target)) {
@@ -13686,16 +13942,27 @@ async function handlePlayCheck(args) {
 `
     );
   } else if (enrichedResult.valid) {
-    console.log(`\u2713 ${playName} passed cloud play check`);
+    const summary = enrichedResult.summary?.trim();
+    console.log(
+      summary ? `\u2713 ${playName} valid \u2014 ${summary}` : `\u2713 ${playName} passed cloud play check`
+    );
     if (enrichedResult.artifactHash) {
       console.log(`  artifact: ${enrichedResult.artifactHash.slice(0, 12)}`);
     }
+    printPlayTriggers(enrichedResult.triggers);
+    printRecognizedSummary(enrichedResult.recognized);
+    printPlayCheckIssues(enrichedResult.issues, (line) => console.log(line));
     printToolGetterHints(enrichedResult.toolGetterHints);
   } else {
     console.error(`\u2717 ${playName} failed cloud play check`);
-    for (const error of enrichedResult.errors) {
+    const { unstructuredErrors } = partitionMirroredErrors(
+      enrichedResult.errors,
+      enrichedResult.issues
+    );
+    for (const error of unstructuredErrors) {
       console.error(`  ${error}`);
     }
+    printPlayCheckIssues(enrichedResult.issues, (line) => console.error(line));
     printToolGetterHints(enrichedResult.toolGetterHints);
   }
   return enrichedResult.valid ? 0 : 1;
@@ -16215,7 +16482,7 @@ function canInlineRunJavascript(command) {
   return true;
 }
 function renderExtractFunction(command, indentSpaces) {
-  return command.extract_js ? `({ row, result, data, raw, pick, extract, extractList, target, get }) => { const input = row; const context = row;
+  return command.extract_js ? `({ row, result, data, raw, pick, extract, extractList, target, get }) => { const input = row; const context = row; const output_data = __dlLegacyOutputData(result, raw);
 ${indent(renderJavascriptBody(command.extract_js), indentSpaces)}
     }` : "null";
 }
@@ -16843,8 +17110,13 @@ function helperSource() {
     `  __dlPushCandidate(candidates, record.data);`,
     `  __dlPushCandidate(candidates, record.result);`,
     `  __dlPushCandidate(candidates, record.output);`,
+    `  __dlPushCandidate(candidates, __dlGetByPath(record, 'data.data'));`,
     `  __dlPushCandidate(candidates, __dlGetByPath(record, 'result.data'));`,
+    `  __dlPushCandidate(candidates, __dlGetByPath(record, 'result.data.data'));`,
+    `  __dlPushCandidate(candidates, __dlGetByPath(record, 'output.data'));`,
+    `  __dlPushCandidate(candidates, __dlGetByPath(record, 'output.data.data'));`,
     `  __dlPushCandidate(candidates, __dlGetByPath(record, 'output.body'));`,
+    `  __dlPushCandidate(candidates, __dlGetByPath(record, 'output.body.data'));`,
     `  __dlPushCandidate(candidates, __dlGetByPath(record, 'toolResponse.raw'));`,
     `  __dlPushCandidate(candidates, __dlGetByPath(record, 'toolOutput.raw'));`,
     `  return candidates;`,
@@ -17241,13 +17513,37 @@ function helperSource() {
     `  return { ...defaults, ...(existing as Record<string, unknown>) };`,
     `}`,
     ``,
+    `function __dlCompactJavascriptContext(value: unknown, depth = 0): unknown {`,
+    `  if (depth > 8) return '[Object]';`,
+    `  if (typeof value === 'string') return value.length > 20000 ? value.slice(0, 20000) + '...[truncated]' : value;`,
+    `  if (!value || typeof value !== 'object') return value;`,
+    `  if (Array.isArray(value)) {`,
+    `    const limit = depth <= 2 ? 25 : 10;`,
+    `    const items = value.slice(0, limit).map((entry) => __dlCompactJavascriptContext(entry, depth + 1));`,
+    `    if (value.length > limit) items.push({ __deepline_truncated_items: value.length - limit });`,
+    `    return items;`,
+    `  }`,
+    `  const out: Record<string, unknown> = {};`,
+    `  let count = 0;`,
+    `  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {`,
+    `    count += 1;`,
+    `    if (count > 80) {`,
+    `      out.__deepline_truncated_fields = count - 80;`,
+    `      break;`,
+    `    }`,
+    `    out[key] = __dlCompactJavascriptContext(entry, depth + 1);`,
+    `  }`,
+    `  return out;`,
+    `}`,
+    ``,
     `function __dlRuntimePayload(tool: string, payload: Record<string, unknown>, row: Record<string, unknown>): Record<string, unknown> {`,
     `  if (tool !== 'run_javascript') return payload;`,
+    `  const compactRow = __dlCompactJavascriptContext(row) as Record<string, unknown>;`,
     `  return {`,
     `    ...payload,`,
-    `    row: __dlMergeContextRecord(payload.row, row),`,
-    `    input: __dlMergeContextRecord(payload.input, row),`,
-    `    context: __dlMergeContextRecord(payload.context, row),`,
+    `    row: __dlMergeContextRecord(payload.row, compactRow),`,
+    `    input: __dlMergeContextRecord(payload.input, compactRow),`,
+    `    context: __dlMergeContextRecord(payload.context, compactRow),`,
     `  };`,
     `}`,
     ``,
@@ -18250,6 +18546,125 @@ function enrichOutputJson(exportResult) {
     ...exportResult.partial ? { rows: exportResult.rows, partial: true } : {}
   };
 }
+function readFirstEnrichDatasetActions(value) {
+  const seen = /* @__PURE__ */ new Set();
+  const walk = (candidate, options) => {
+    if (!candidate || typeof candidate !== "object" || seen.has(candidate)) {
+      return null;
+    }
+    seen.add(candidate);
+    if (Array.isArray(candidate)) {
+      for (const entry of candidate) {
+        const found = walk(entry, options);
+        if (found) return found;
+      }
+      return null;
+    }
+    const record = candidate;
+    const actions = isRecord7(record.actions) ? record.actions : null;
+    const query = isRecord7(actions?.query) ? actions.query : null;
+    if (query?.kind === "deepline_db_query") {
+      return {
+        dataset: record,
+        query,
+        ...isRecord7(actions?.exportCsv) ? { exportCsv: actions.exportCsv } : {}
+      };
+    }
+    if (options.allowLegacy && record.kind === "dataset" && typeof record.queryDatasetCommand === "string" && record.queryDatasetCommand.trim()) {
+      return {
+        dataset: record,
+        queryDatasetCommand: record.queryDatasetCommand.trim(),
+        ...typeof record.slowExportAsCsvCommand === "string" && record.slowExportAsCsvCommand.trim() ? { slowExportAsCsvCommand: record.slowExportAsCsvCommand.trim() } : {}
+      };
+    }
+    for (const [key, entry] of Object.entries(record)) {
+      if (key === "preview") {
+        continue;
+      }
+      const found = walk(entry, options);
+      if (found) return found;
+    }
+    return null;
+  };
+  const modern = walk(value, { allowLegacy: false });
+  if (modern) {
+    return modern;
+  }
+  seen.clear();
+  return walk(value, { allowLegacy: true });
+}
+function actionStringField(record, key) {
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function parseSqlFromDbQueryCommand(command) {
+  if (!command) {
+    return null;
+  }
+  const match = command.match(/\s--sql\s+('(?:'\\''|[^'])*'|"(?:"\\"|[^"])*")/);
+  if (!match?.[1]) {
+    return null;
+  }
+  const raw = match[1];
+  if (raw.startsWith("'") && raw.endsWith("'")) {
+    return raw.slice(1, -1).replace(/'\\''/g, "'");
+  }
+  return decodeStringLiteral(raw);
+}
+function enrichCustomerDbJson(input2) {
+  const actions = readFirstEnrichDatasetActions(input2.status);
+  if (!actions) {
+    return null;
+  }
+  const query = actions.query ?? {};
+  const dataset = actions.dataset;
+  const sql = actionStringField(query, "sql") ?? parseSqlFromDbQueryCommand(actions.queryDatasetCommand);
+  const datasetPath = actionStringField(query, "datasetPath") ?? actionStringField(dataset, "path") ?? actionStringField(dataset, "tableNamespace");
+  const api = isRecord7(query.api) ? query.api : null;
+  const apiPath = actionStringField(api ?? {}, "path") ?? "/api/v2/db/query";
+  const apiMethod = actionStringField(api ?? {}, "method") ?? "POST";
+  if (!datasetPath) {
+    return null;
+  }
+  const maxRows = typeof query.maxRows === "number" && Number.isFinite(query.maxRows) ? Math.trunc(query.maxRows) : void 0;
+  const runId = extractRunId(input2.status) ?? actionStringField(actions.exportCsv ?? {}, "runId");
+  const exportDatasetPath = actionStringField(actions.exportCsv ?? {}, "datasetPath") ?? datasetPath;
+  const tableNamespace = actionStringField(query, "tableNamespace") ?? actionStringField(dataset, "tableNamespace");
+  const sqlTableName = actionStringField(query, "sqlTableName");
+  const sqlQualifiedTableName = actionStringField(
+    query,
+    "sqlQualifiedTableName"
+  );
+  const command = actions.queryDatasetCommand ?? (sql ? `deepline db query --sql ${shellSingleQuote2(sql)}${maxRows !== void 0 ? ` --max-rows ${maxRows}` : ""} --json` : null);
+  return {
+    runId,
+    datasetPath,
+    ...tableNamespace ? { tableNamespace } : {},
+    ...sqlTableName ? { sqlTableName } : {},
+    ...sqlQualifiedTableName ? { sqlQualifiedTableName } : {},
+    ...sql ? { sql } : {},
+    ...actions.query ? {
+      api: {
+        method: apiMethod,
+        path: apiPath,
+        url: `${input2.client.baseUrl.replace(/\/$/, "")}${apiPath}`
+      }
+    } : {},
+    ...maxRows !== void 0 ? { maxRows } : {},
+    ...command ? { command } : {},
+    ...actions.exportCsv || actions.slowExportAsCsvCommand ? {
+      export: {
+        datasetPath: exportDatasetPath,
+        ...actions.slowExportAsCsvCommand ? { command: actions.slowExportAsCsvCommand } : runId && input2.outputPath ? {
+          command: `deepline runs export ${runId} --dataset ${shellSingleQuote2(
+            exportDatasetPath
+          )} --out ${shellSingleQuote2(resolve9(input2.outputPath))}`
+        } : {},
+        action: actions.exportCsv ?? {}
+      }
+    } : {}
+  };
+}
 function enrichReportJson(report) {
   if (!report) {
     return {};
@@ -18270,6 +18685,78 @@ function enrichReportJson(report) {
     } : {}
   };
 }
+function sqlStringLiteral(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+function failureAliasFromCellMeta(cellMeta) {
+  if (!isRecord7(cellMeta)) {
+    return null;
+  }
+  for (const [alias, meta] of Object.entries(cellMeta)) {
+    if (!isRecord7(meta)) {
+      continue;
+    }
+    const failure = failureCellFromMeta(meta, {});
+    if (!failure) {
+      continue;
+    }
+    return {
+      alias,
+      ...typeof failure.error === "string" ? { error: failure.error } : {},
+      ...typeof failure.operation === "string" ? { operation: failure.operation } : {},
+      ...typeof failure.provider === "string" ? { provider: failure.provider } : {}
+    };
+  }
+  return null;
+}
+async function collectCustomerDbFailureJobs(input2) {
+  const customerDb = enrichCustomerDbJson({
+    status: input2.status,
+    client: input2.client
+  });
+  if (!customerDb?.runId || !customerDb.sqlQualifiedTableName) {
+    return [];
+  }
+  const fallbackAliases = collectHardFailureAliasSpecs(input2.config);
+  const fallbackAlias = fallbackAliases[0]?.alias ?? "enrich";
+  const aliasIndexByName = new Map(
+    fallbackAliases.map((spec, index) => [normalizeAlias2(spec.alias), index])
+  );
+  const sql = `select _input_index, _status, _error, _cell_meta from ${customerDb.sqlQualifiedTableName} where _run_id = ${sqlStringLiteral(customerDb.runId)} and (_error is not null or lower(coalesce(_status, '')) in ('failed', 'error')) order by _input_index limit 1000`;
+  const result = await input2.client.queryCustomerDb({
+    sql,
+    maxRows: 1e3
+  });
+  const rows = Array.isArray(result.rows) ? result.rows : [];
+  const failedRows = rows.filter((row) => {
+    const status = typeof row._status === "string" ? row._status.trim().toLowerCase() : "";
+    return typeof row._error === "string" && row._error.trim() || status === "failed" || status === "error";
+  });
+  return failedRows.map((row, index) => {
+    const metaFailure = failureAliasFromCellMeta(row._cell_meta);
+    const alias = metaFailure?.alias ?? fallbackAlias;
+    const normalizedAlias = normalizeAlias2(alias);
+    const rowId = typeof row._input_index === "number" ? row._input_index : typeof row._input_index === "string" && row._input_index.trim() ? Number.parseInt(row._input_index, 10) : index;
+    const rawError = metaFailure?.error ?? (typeof row._error === "string" && row._error.trim() ? row._error.trim() : `Column status: ${String(row._status ?? "failed")}`);
+    const message = enrichFailureMessageWithOperation(
+      rawError,
+      metaFailure?.operation ?? fallbackAliases.find(
+        (spec) => normalizeAlias2(spec.alias) === normalizedAlias
+      )?.operation
+    );
+    return {
+      job_id: `row-${Number.isFinite(rowId) ? rowId : index}-${normalizedAlias || "enrich"}`,
+      row_id: Number.isFinite(rowId) ? rowId : index,
+      col_index: aliasIndexByName.get(normalizedAlias) ?? 0,
+      column: alias,
+      status: "failed",
+      last_error: message,
+      error: message,
+      ...metaFailure?.operation ? { operation: metaFailure.operation } : {},
+      ...metaFailure?.provider ? { provider: metaFailure.provider } : {}
+    };
+  });
+}
 async function buildEnrichFailureReport(input2) {
   const fallbackRowsInfo = input2.exportResult ? null : extractCanonicalRowsInfo(input2.status);
   return maybeEmitEnrichFailureReport({
@@ -18371,9 +18858,7 @@ async function writeSlimBatchedRuntimeCsv(input2) {
     };
     cleanRows[rowIndex] = {
       ...baseRow,
-      ...Object.fromEntries(
-        Object.entries(mergeRow).map(compactOverlayCell)
-      )
+      ...Object.fromEntries(Object.entries(mergeRow).map(compactOverlayCell))
     };
   }
   const columns = dataExportColumns(
@@ -18797,6 +19282,11 @@ function collectWaterfallAliasSpecs(config) {
     aliases.push({
       alias,
       childAliases: activeChildren.map((child) => child.alias).filter(Boolean),
+      childRunIfJsByAlias: new Map(
+        activeChildren.map(
+          (child) => [child.alias, child.run_if_js]
+        )
+      ),
       childToolsByAlias: new Map(
         activeChildren.map(
           (child) => [child.alias, child.tool.trim()]
@@ -19031,7 +19521,8 @@ function collectEmptyWaterfallIssues(input2) {
   });
   const issues = [];
   aliases.forEach((spec) => {
-    if (waterfallExecutionSignal(input2.status, spec) === "all_condition_skipped") {
+    const executionSignal = waterfallExecutionSignal(input2.status, spec);
+    if (executionSignal === "all_condition_skipped" || executionSignal === "unknown" && waterfallChildrenAreStaticallySkipped(spec)) {
       return;
     }
     const logicalRows = /* @__PURE__ */ new Map();
@@ -19073,6 +19564,22 @@ function collectEmptyWaterfallIssues(input2) {
   });
   return issues;
 }
+function waterfallChildrenAreStaticallySkipped(spec) {
+  const childAliases = spec.childAliases ?? [];
+  if (childAliases.length === 0 || !spec.childRunIfJsByAlias) {
+    return false;
+  }
+  return childAliases.every(
+    (alias) => runIfJsAlwaysReturnsFalse(spec.childRunIfJsByAlias?.get(alias))
+  );
+}
+function runIfJsAlwaysReturnsFalse(source) {
+  if (typeof source !== "string") {
+    return false;
+  }
+  const normalized = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|\s)\/\/.*$/gm, "").trim();
+  return /^(?:return\s+)?\(?\s*false\s*\)?\s*;?$/.test(normalized);
+}
 function waterfallExecutionSignal(status, spec) {
   const childAliases = spec.childAliases ?? [];
   if (childAliases.length === 0) {
@@ -19349,10 +19856,11 @@ function rewriteEnrichJsonStatus(input2) {
   if (failedRows === 0 || !isRecord7(rewritten)) {
     return rewritten;
   }
+  const partialStatus = selectedRows > 0 && failedRows < selectedRows ? "partial_success" : "failed";
   return {
     ...rewritten,
-    ...rewritten.status === "completed" ? { status: "failed" } : {},
-    ...isRecord7(rewritten.run) && rewritten.run.status === "completed" ? { run: { ...rewritten.run, status: "failed" } } : {}
+    ...rewritten.status === "completed" || rewritten.status === "failed" ? { status: partialStatus } : {},
+    ...isRecord7(rewritten.run) && (rewritten.run.status === "completed" || rewritten.run.status === "failed") ? { run: { ...rewritten.run, status: partialStatus } } : {}
   };
 }
 function summarizeFailedJobError(value) {
@@ -19388,6 +19896,12 @@ function collectEnrichFollowUpCommands(input2) {
       command: `deepline runs get ${input2.runId} --full --json`
     });
   }
+  if (input2.runId && input2.outputPath) {
+    addEnrichRowsExportFollowUpCommand(commands, seen, {
+      runId: input2.runId,
+      outputPath: input2.outputPath
+    });
+  }
   collectDatasetFollowUpCommands(input2.status, {
     runId: input2.runId,
     outputPath: input2.outputPath,
@@ -19396,17 +19910,17 @@ function collectEnrichFollowUpCommands(input2) {
     path: "result",
     depth: 0
   });
-  if (input2.runId && input2.outputPath && !commands.some((command) => command.label === "export enrich rows")) {
-    addEnrichFollowUpCommand(commands, seen, {
-      label: "export enrich rows",
-      path: GENERATED_ENRICH_ROWS_TABLE_NAMESPACE,
-      command: `deepline runs export ${input2.runId} --dataset ${GENERATED_ENRICH_ROWS_TABLE_NAMESPACE} --out ${shellSingleQuote2(
-        resolve9(input2.outputPath)
-      )}`
-    });
-  }
   return commands.slice(0, 8);
 }
+function addEnrichRowsExportFollowUpCommand(commands, seen, input2) {
+  addEnrichFollowUpCommand(commands, seen, {
+    label: "export enrich rows",
+    path: GENERATED_ENRICH_ROWS_TABLE_NAMESPACE,
+    command: `deepline runs export ${input2.runId} --dataset ${GENERATED_ENRICH_ROWS_TABLE_NAMESPACE} --out ${shellSingleQuote2(
+      resolve9(input2.outputPath)
+    )}`
+  });
+}
 function sidecarEnrichRowsExportPath(outputPath) {
   const resolved = resolve9(outputPath);
   const ext = extname(resolved) || ".csv";
@@ -19547,7 +20061,15 @@ async function maybeEmitEnrichFailureReport(input2) {
     status: input2.status,
     rowRange: input2.statusRowRange ?? input2.rowRange
   });
-  const jobs = rowJobs.length > 0 || statusJobs.length > 0 || input2.status === void 0 ? mergeEnrichFailureJobs(rowJobs, statusJobs) : [];
+  const customerDbJobs = input2.status === void 0 || rowJobs.length > 0 || statusJobs.length > 0 ? [] : await collectCustomerDbFailureJobs({
+    client: input2.client,
+    status: input2.status,
+    config: input2.config
+  });
+  const jobs = rowJobs.length > 0 || statusJobs.length > 0 || customerDbJobs.length > 0 || input2.status === void 0 ? mergeEnrichFailureJobs(
+    mergeEnrichFailureJobs(rowJobs, statusJobs),
+    customerDbJobs
+  ) : [];
   if (jobs.length === 0 && enrichIssues.length === 0) {
     return null;
   }
@@ -19653,6 +20175,8 @@ async function fetchBackingRowsForCsvExport(input2) {
   const hasExplicitExpectedRows = typeof input2.expectedRows === "number" && input2.expectedRows > 0;
   const minimumExpectedRows = hasExplicitExpectedRows ? Math.trunc(Number(input2.expectedRows)) : input2.rowsInfo.totalRows;
   let lastExpectedTotal = minimumExpectedRows;
+  const expectedSourceRowStart = input2.sourceRowStart ?? 0;
+  const expectedSourceRowEnd = expectedSourceRowStart + Math.max(0, minimumExpectedRows) - 1;
   for (; ; ) {
     const sheetRows = [];
     let offset = 0;
@@ -19668,19 +20192,39 @@ async function fetchBackingRowsForCsvExport(input2) {
       });
       sheetRows.push(...page.rows);
       const summaryTotal = page.summary?.stats?.total;
-      if (typeof summaryTotal === "number" && Number.isFinite(summaryTotal)) {
+      if (!hasExplicitExpectedRows && typeof summaryTotal === "number" && Number.isFinite(summaryTotal)) {
         expectedTotal = Math.max(expectedTotal, Math.trunc(summaryTotal));
       }
-      if (page.rows.length < ENRICH_EXPORT_PAGE_SIZE || sheetRows.length >= expectedTotal) {
+      let hasRequiredRows = sheetRows.length >= expectedTotal;
+      if (hasExplicitExpectedRows) {
+        const exportableRows = coalesceExportableSheetRows(
+          sheetRows.map((row) => exportableSheetRow2(row, input2.sourceRowStart ?? 0)).filter((row) => Boolean(row)),
+          input2.sourceRowStart ?? 0
+        ).filter(
+          (row) => sourceRowIndexFromEnrichRow(
+            row,
+            expectedSourceRowStart,
+            expectedSourceRowEnd
+          ) !== null
+        );
+        hasRequiredRows = exportableRows.length >= minimumExpectedRows;
+      }
+      if (page.rows.length < ENRICH_EXPORT_PAGE_SIZE || hasRequiredRows) {
         break;
       }
       offset += page.rows.length;
     }
     const rawRows = sheetRows.map((row) => exportableSheetRow2(row, input2.sourceRowStart ?? 0)).filter((row) => Boolean(row));
-    const rows = coalesceExportableSheetRows(
-      rawRows,
-      input2.sourceRowStart ?? 0
-    );
+    let rows = coalesceExportableSheetRows(rawRows, input2.sourceRowStart ?? 0);
+    if (hasExplicitExpectedRows) {
+      rows = rows.filter(
+        (row) => sourceRowIndexFromEnrichRow(
+          row,
+          expectedSourceRowStart,
+          expectedSourceRowEnd
+        ) !== null
+      );
+    }
     lastRows = rows;
     lastExpectedTotal = expectedTotal;
     const requiredExportRows = hasExplicitExpectedRows ? minimumExpectedRows : expectedTotal;
@@ -20334,6 +20878,7 @@ function registerEnrichCommand(program) {
         }
         if (input2.json) {
           runArgs.push("--json");
+          runArgs.push("--full");
         } else {
           runArgs.push("--logs");
         }
@@ -20456,6 +21001,11 @@ function registerEnrichCommand(program) {
                     partial: true
                   } : {}
                 } : null,
+                customer_db: enrichCustomerDbJson({
+                  status: chunk.status,
+                  client: client2,
+                  outputPath: enrichIssueFollowUpOutputPath ?? committedExportResult2?.path ?? outputPath
+                }),
                 ...enrichReportJson(failureReport3)
               });
             } else {
@@ -20530,6 +21080,11 @@ function registerEnrichCommand(program) {
               enrichedRows: totalEnrichedRows,
               path: finalExportResult.path
             } : null,
+            customer_db: enrichCustomerDbJson({
+              status: lastStatus,
+              client: client2,
+              outputPath: enrichIssueFollowUpOutputPath ?? finalExportResult?.path ?? outputPath
+            }),
             ...enrichReportJson(failureReport2)
           });
         }
@@ -20569,6 +21124,11 @@ function registerEnrichCommand(program) {
             ok: false,
             run: status,
             output: enrichOutputJson(committedExportResult2),
+            customer_db: enrichCustomerDbJson({
+              status,
+              client: client2,
+              outputPath: enrichIssueFollowUpOutputPath ?? committedExportResult2?.path ?? outputPath
+            }),
             ...enrichReportJson(failureReport2)
           });
         }
@@ -20599,6 +21159,11 @@ function registerEnrichCommand(program) {
           ok: !failureReport2,
           run,
           output: enrichOutputJson(committedExportResult2),
+          customer_db: enrichCustomerDbJson({
+            status,
+            client: client2,
+            outputPath: enrichIssueFollowUpOutputPath ?? committedExportResult2?.path ?? outputPath
+          }),
           ...enrichReportJson(failureReport2)
         });
         if (failureReport2) {
@@ -21499,72 +22064,494 @@ Examples:
 }
 
 // src/cli/commands/monitors.ts
+import { readFileSync as readFileSync9 } from "fs";
+import { createInterface } from "readline/promises";
 var FORBIDDEN_AS_API_ERROR = { forbiddenAsApiError: true };
+var JSON_OPTION_DESCRIPTION = "Emit JSON output. Also automatic when stdout is piped";
+function withJsonOption(command) {
+  return command.option("--json", JSON_OPTION_DESCRIPTION);
+}
+var COMPACT_OPTION_DESCRIPTION = "Ask the server for high-signal fields only (smaller output for agent loops)";
 function buildHttpClient() {
   return new HttpClient(resolveConfig());
 }
-function parseJsonObjectArg(raw, flag) {
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (error) {
-    throw new Error(
-      `${flag} must be a JSON object. ${error instanceof Error ? error.message : String(error)}`
-    );
+var MonitorsUsageError = class extends Error {
+  code = "MONITORS_USAGE_ERROR";
+  constructor(message) {
+    super(message);
+    this.name = "MonitorsUsageError";
   }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`${flag} must be a JSON object.`);
+};
+var MonitorDryRunUnsupportedError = class extends Error {
+  code = "MONITOR_DRY_RUN_UNSUPPORTED";
+  constructor(message) {
+    super(message);
+    this.name = "MonitorDryRunUnsupportedError";
   }
-  return parsed;
-}
-function encodeKey(key) {
-  return encodeURIComponent(key);
+};
+function monitorsErrorExitCode(error) {
+  if (error instanceof MonitorsUsageError) return 2;
+  if (error instanceof AuthError) return 3;
+  if (error instanceof DeeplineError) {
+    const status = error.statusCode;
+    if (status === 401 || status === 403) return 3;
+    if (status === 404) return 4;
+    if (status === 400 || status === 422) return 7;
+    return 5;
+  }
+  return 5;
 }
-async function handleMonitorsTools(options) {
-  const http = buildHttpClient();
-  const params = new URLSearchParams();
-  if (options.provider) params.set("provider", options.provider);
-  if (options.tool) params.set("tool", options.tool);
-  if (options.search) params.set("search", options.search);
-  if (options.limit) params.set("limit", options.limit);
-  const query = params.toString();
-  const payload = await http.request(
-    `/api/v2/monitors/tools${query ? `?${query}` : ""}`,
-    { method: "GET", ...FORBIDDEN_AS_API_ERROR }
-  );
-  printCommandEnvelope(payload, { json: options.json });
+function monitorsFailureNextCommand(error, exitCode) {
+  if (error instanceof DeeplineError && error.code === "monitor_access_required") {
+    return "deepline monitors status";
+  }
+  if (exitCode === 3) return "deepline auth status --json";
+  if (exitCode === 4) return "deepline monitors list --status all --json";
+  return void 0;
 }
-async function handleMonitorsCheck(definition, options) {
-  const http = buildHttpClient();
-  const body = parseJsonObjectArg(definition, "--definition");
+function readValidationIssues(error) {
+  if (!(error instanceof DeeplineError)) return [];
+  const response = asRecord(asRecord(error.details)?.response);
+  const issues = Array.isArray(response?.issues) ? response.issues : [];
+  return issues.flatMap((raw) => {
+    const issue = asRecord(raw);
+    if (!issue) return [];
+    return [
+      {
+        ...asString(issue.path) ? { path: asString(issue.path) } : {},
+        ...asString(issue.message) ? { message: asString(issue.message) } : {}
+      }
+    ];
+  });
+}
+function reportMonitorsFailure(error) {
+  const exitCode = monitorsErrorExitCode(error);
+  const next = monitorsFailureNextCommand(error, exitCode);
+  const wantsJson = shouldEmitJson(process.argv.includes("--json"));
+  if (wantsJson) {
+    const payload = errorToJsonPayload(error);
+    printJson({
+      ok: false,
+      exitCode,
+      ...next ? { next } : {},
+      error: payload.error
+    });
+  } else {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Error: ${message}
+`);
+    for (const issue of readValidationIssues(error)) {
+      process.stderr.write(
+        `  - ${issue.path ? `${issue.path}: ` : ""}${issue.message ?? ""}
+`
+      );
+    }
+    if (next) process.stderr.write(`Next: ${next}
+`);
+  }
+  process.exitCode = exitCode;
+}
+function monitorsAction(handler) {
+  return async (...args) => {
+    try {
+      await handler(...args);
+    } catch (error) {
+      reportMonitorsFailure(error);
+    }
+  };
+}
+function parseJsonObjectArg(raw, argLabel) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new MonitorsUsageError(
+      `${argLabel} must be a JSON object. ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new MonitorsUsageError(`${argLabel} must be a JSON object.`);
+  }
+  return parsed;
+}
+function resolveMonitorJsonBody(input2) {
+  const readFile3 = input2.readFile ?? ((path) => readFileSync9(path, "utf-8"));
+  const readStdin = input2.readStdin ?? (() => readFileSync9(0, "utf-8"));
+  if (input2.positional !== void 0 && input2.file !== void 0) {
+    throw new MonitorsUsageError(
+      `Pass exactly one source for ${input2.argLabel}: the positional JSON or --file, not both.`
+    );
+  }
+  if (input2.positional !== void 0) {
+    return parseJsonObjectArg(input2.positional, input2.argLabel);
+  }
+  if (input2.file !== void 0) {
+    if (input2.file === "-") {
+      return parseJsonObjectArg(readStdin(), `${input2.argLabel} (stdin)`);
+    }
+    let raw;
+    try {
+      raw = readFile3(input2.file);
+    } catch (error) {
+      throw new MonitorsUsageError(
+        `Could not read --file ${input2.file}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    return parseJsonObjectArg(raw, `${input2.argLabel} (--file ${input2.file})`);
+  }
+  throw new MonitorsUsageError(
+    `${input2.command} needs ${input2.argLabel} (a JSON object). Pass it positionally:
+  ${input2.command} '{"key":"my-monitor","tool":"theirstack.saved_search_webhook","payload":{}}'
+or from a file / stdin:
+  ${input2.command} --file monitor.json
+  cat monitor.json | ${input2.command} --file -`
+  );
+}
+function encodeKey(key) {
+  return encodeURIComponent(key);
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function asString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function asFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function yesNo(value) {
+  if (value === true) return "yes";
+  if (value === false) return "no";
+  return "unknown";
+}
+function readDeployOutputContract(payload) {
+  const contract = asRecord(payload.output_contract);
+  if (!contract) return { streams: [] };
+  const rawOutputs = Array.isArray(contract.outputs) ? contract.outputs : [];
+  const streams = rawOutputs.flatMap((raw) => {
+    const output2 = asRecord(raw);
+    const stream = output2 ? asString(output2.stream) : void 0;
+    const table = output2 ? asString(output2.table) : void 0;
+    if (!output2 || !stream || !table) return [];
+    const columns = Array.isArray(output2.columns) ? output2.columns.flatMap((rawColumn) => {
+      const column = asRecord(rawColumn);
+      const name = column ? asString(column.name) : void 0;
+      return name ? [name] : [];
+    }) : [];
+    return [
+      {
+        stream,
+        table,
+        columns,
+        isEvent: output2.is_event_stream === true,
+        matchesPayload: output2.matches_payload === true
+      }
+    ];
+  });
+  return { tool: asString(contract.tool), streams };
+}
+function renderMonitorDeployCompletion(payload) {
+  const monitor = asRecord(payload.monitor);
+  const key = monitor ? asString(monitor.key) : void 0;
+  const { tool, streams } = readDeployOutputContract(payload);
+  if (!key || streams.length === 0) return void 0;
+  const toolId = tool ?? (monitor ? asString(monitor.tool) : void 0) ?? "<tool>";
+  const name = monitor ? asString(monitor.name) : void 0;
+  const status = monitor ? asString(monitor.status) : void 0;
+  const eventStreams = streams.filter((stream) => stream.isEvent);
+  const matched = eventStreams.filter((stream) => stream.matchesPayload);
+  const shown = matched.length ? matched : eventStreams.length ? eventStreams : streams;
+  const primary = shown[0];
+  const lines = [
+    `\u2713 Deployed monitor "${key}"${name ? ` (${name})` : ""} \u2014 tool ${toolId}${status ? `, status ${status}` : ""}`,
+    "",
+    "Output \u2192 Customer DB:"
+  ];
+  for (const stream of shown) {
+    lines.push(`  ${stream.table}  (stream: ${stream.stream})`);
+    lines.push(
+      `    columns: ${stream.columns.length ? stream.columns.join(", ") : "(promoted dynamically as events arrive)"}`
+    );
+  }
+  lines.push(
+    "",
+    "This monitor streams new rows into your Customer DB \u2014 there is no manual run.",
+    "Next:",
+    "  \u2022 Query the table above directly, or",
+    "  \u2022 Run a play on each new row (third arg to definePlay in your .play.ts):",
+    `      sqlListeners: [{ id: '${primary.stream}', tool: '${toolId}', stream: '${primary.stream}', operations: ['INSERT'] }]`,
+    "    The changed row arrives to your handler as the sqlListener event's `after`.",
+    "",
+    "Reuse: many plays can bind to this one stream \u2014 you do NOT need a separate",
+    "monitor per play. Before deploying another monitor on this tool, run",
+    "`deepline monitors list` and reuse an existing one that covers your scope."
+  );
+  return `${lines.join("\n")}
+`;
+}
+function renderMonitorDeployPlan(payload) {
+  const valid = payload.valid !== false;
+  const lines = [
+    "DRY RUN \u2014 nothing was deployed.",
+    valid ? "Definition: valid" : "Definition: INVALID"
+  ];
+  if (!valid) {
+    const issues = Array.isArray(payload.issues) ? payload.issues : [];
+    for (const raw of issues) {
+      const issue = asRecord(raw);
+      const path = issue ? asString(issue.path) : void 0;
+      const message = issue ? asString(issue.message) : void 0;
+      if (message) lines.push(`  - ${path ? `${path}: ` : ""}${message}`);
+    }
+  }
+  const estimate = asRecord(payload.deploy_cost_estimate);
+  const credits = estimate ? asFiniteNumber(estimate.credits) : void 0;
+  if (credits !== void 0) {
+    const note = estimate ? asString(estimate.note) : void 0;
+    lines.push(
+      `Deploy cost: would cost ${credits} Deepline credits${note ? ` \u2014 ${note}` : ""}.`
+    );
+  } else {
+    lines.push(
+      "Deploy cost: estimate unavailable from this server (validation only)."
+    );
+  }
+  const candidates = Array.isArray(payload.reuse_candidates) ? payload.reuse_candidates : [];
+  const candidateLines = candidates.flatMap((raw) => {
+    const candidate = asRecord(raw);
+    const key = candidate ? asString(candidate.key) : void 0;
+    if (!candidate || !key) return [];
+    const name = asString(candidate.name);
+    const status = asString(candidate.status);
+    const covers = asString(candidate.covers);
+    return [
+      `  ${key}${name ? ` (${name})` : ""}${status ? ` \u2014 ${status}` : ""}${covers ? `; covers ${covers}` : ""}`
+    ];
+  });
+  if (candidateLines.length > 0) {
+    lines.push(
+      "",
+      "You may already have a monitor covering this \u2014 check before deploying:",
+      ...candidateLines,
+      "  Inspect: deepline monitors get <key> --json"
+    );
+  }
+  lines.push(
+    "",
+    valid ? "Deploy for real: re-run this command without --dry-run." : "Fix the definition, then re-run this command."
+  );
+  return `${lines.join("\n")}
+`;
+}
+function renderMonitorDeletePlan(payload, fallbackKey) {
+  const plan = asRecord(payload.plan);
+  const key = (plan ? asString(plan.monitor_key) : void 0) ?? fallbackKey;
+  const lines = [
+    "DRY RUN \u2014 nothing was deleted.",
+    `Delete plan for monitor "${key}":`,
+    `  delete Deepline record: ${yesNo(plan?.would_delete_record)}`,
+    `  deprovision upstream provider resource: ${yesNo(plan?.would_deprovision_upstream)}`,
+    "",
+    `Delete for real: deepline monitors delete ${key} --yes`
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function renderMonitorReactivatePlan(payload, key) {
+  const estimate = asRecord(payload.cost_estimate);
+  const credits = estimate ? asFiniteNumber(estimate.credits) : void 0;
+  const lines = [
+    "DRY RUN \u2014 nothing was reactivated.",
+    credits !== void 0 ? `Reactivate cost: would cost ${credits} Deepline credits.` : "Reactivate cost: estimate unavailable from this server.",
+    "",
+    `Reactivate for real: deepline monitors reactivate ${key}`
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function assertMonitorDryRunAcknowledged(payload, context) {
+  if (payload.dry_run === true) return;
+  throw new MonitorDryRunUnsupportedError(
+    `${context.command} --dry-run: the server response did not acknowledge dry-run mode (missing "dry_run": true). This Deepline server may not support --dry-run for ${context.mutation}, so the response cannot be trusted as a plan. Nothing was rendered as a plan. Verify current state with \`deepline monitors get <key> --json\`, and re-run without --dry-run only when you intend the real ${context.mutation}.`
+  );
+}
+function monitorDeleteRequiresYesError(key, options = {}) {
+  const flags = options.localOnly ? " --local-only" : "";
+  return new MonitorsUsageError(
+    `monitors delete is destructive: it deletes monitor "${key}"${options.localOnly ? " (Deepline record only)" : " and deprovisions its upstream provider resource"}. Non-interactive runs must confirm with --yes:
+  deepline monitors delete ${key}${flags} --yes
+Preview the plan first with:
+  deepline monitors delete ${key}${flags} --dry-run`
+  );
+}
+async function handleMonitorsStatus(options) {
+  const http = buildHttpClient();
   const payload = await http.request(
-    "/api/v2/monitors/check",
-    { method: "POST", body, ...FORBIDDEN_AS_API_ERROR }
+    "/api/v2/monitors/access",
+    { method: "GET" }
+  );
+  const hasAccess = payload.has_access === true;
+  const reason = typeof payload.reason === "string" && payload.reason.trim() ? payload.reason.trim() : void 0;
+  const text = hasAccess ? `\u2713 You have access to Deepline Monitors${reason ? `
+  ${reason}` : ""}
+` : `\u2717 No access to Deepline Monitors${reason ? ` \u2014 ${reason}` : ""}
+`;
+  printCommandEnvelope(
+    { has_access: hasAccess, ...reason ? { reason } : {} },
+    { json: options.json, text }
   );
-  printCommandEnvelope(payload, { json: options.json });
+  if (!hasAccess) {
+    process.exitCode = 1;
+  }
 }
-async function handleMonitorsDeploy(definition, options) {
+function renderAvailableToolsText(payload) {
+  const tools = Array.isArray(payload.tools) ? payload.tools : null;
+  if (!tools) return void 0;
+  const returned = asFiniteNumber(payload.returned) ?? tools.length;
+  const total = asFiniteNumber(payload.total);
+  const lines = [
+    total !== void 0 ? `Monitor tools you can deploy (${returned} of ${total}):` : "Monitor tools you can deploy:"
+  ];
+  for (const raw of tools) {
+    const entry = asRecord(raw);
+    const id = entry ? asString(entry.tool) : void 0;
+    if (!entry || !id) continue;
+    const name = asString(entry.name) ?? asString(entry.display_name);
+    const deployedCount = asFiniteNumber(entry.deployed_count);
+    lines.push(
+      `  ${id}${name ? ` \u2014 ${name}` : ""}${deployedCount !== void 0 ? `  (deployed: ${deployedCount})` : ""}`
+    );
+  }
+  if (payload.is_truncated === true) {
+    lines.push("List truncated; raise --limit to see more.");
+  }
+  lines.push(
+    "",
+    "Describe one (payload schema + output streams): deepline monitors available <tool-id> --json"
+  );
+  return `${lines.join("\n")}
+`;
+}
+async function handleMonitorsAvailable(toolId, options) {
+  if (toolId !== void 0 && options.tool !== void 0) {
+    if (toolId !== options.tool) {
+      throw new MonitorsUsageError(
+        `Pass the tool id once: got positional "${toolId}" and --tool "${options.tool}". Use: deepline monitors available ${toolId}`
+      );
+    }
+  }
+  const tool = toolId ?? options.tool;
   const http = buildHttpClient();
-  const body = parseJsonObjectArg(definition, "--definition");
+  const params = new URLSearchParams();
+  if (options.provider) params.set("provider", options.provider);
+  if (tool) params.set("tool", tool);
+  if (options.search) params.set("search", options.search);
+  if (options.limit) params.set("limit", options.limit);
+  const compactList = !tool && !options.full;
+  if (compactList || options.compact) params.set("compact", "true");
+  const query = params.toString();
   const payload = await http.request(
-    "/api/v2/monitors/deploy",
-    { method: "POST", body, ...FORBIDDEN_AS_API_ERROR }
+    `/api/v2/monitors/tools${query ? `?${query}` : ""}`,
+    { method: "GET", ...FORBIDDEN_AS_API_ERROR }
   );
-  printCommandEnvelope(payload, { json: options.json });
+  printCommandEnvelope(payload, {
+    json: options.json,
+    // Human list view shows id + name + deployed_count ("deployed: N") so
+    // can-deploy vs already-deployed is visible in one view. Describing a
+    // single tool keeps the full JSON contract (payload schema, streams).
+    text: tool ? void 0 : renderAvailableToolsText(payload)
+  });
+}
+function renderDeployedListText(payload, requestedStatus) {
+  const monitors = Array.isArray(payload.monitors) ? payload.monitors : null;
+  if (!monitors) return void 0;
+  const lines = [
+    monitors.length === 0 ? "No deployed monitors matched." : `Deployed monitors (${monitors.length}):`
+  ];
+  for (const raw of monitors) {
+    const entry = asRecord(raw);
+    const key = entry ? asString(entry.key) ?? asString(entry.monitor_key) : void 0;
+    if (!entry || !key) continue;
+    const status = asString(entry.status);
+    const tool = asString(entry.tool);
+    const name = asString(entry.name);
+    lines.push(
+      `  ${key}${status ? `  ${status}` : ""}${tool ? `  ${tool}` : ""}${name ? `  (${name})` : ""}`
+    );
+  }
+  const applied = asString(payload.status_filter_applied) ?? requestedStatus ?? "active";
+  lines.push(
+    `Status filter: ${applied}${requestedStatus === void 0 && applied === "active" ? " (default)" : ""} \u2014 use --status all to include disabled monitors.`
+  );
+  if (monitors.length > 0) {
+    lines.push("", "Inspect one: deepline monitors get <key> --json");
+  }
+  return `${lines.join("\n")}
+`;
 }
-async function handleDeployedList(options) {
+async function handleMonitorsList(options) {
   const http = buildHttpClient();
   const params = new URLSearchParams();
   if (options.status) params.set("status", options.status);
   if (options.limit) params.set("limit", options.limit);
+  if (options.compact) params.set("compact", "true");
   const query = params.toString();
   const payload = await http.request(
     `/api/v2/monitors/deployed${query ? `?${query}` : ""}`,
     { method: "GET", ...FORBIDDEN_AS_API_ERROR }
   );
+  printCommandEnvelope(payload, {
+    json: options.json,
+    text: renderDeployedListText(payload, options.status)
+  });
+}
+async function handleMonitorsCheck(definition, options) {
+  const http = buildHttpClient();
+  const body = resolveMonitorJsonBody({
+    positional: definition,
+    file: options.file,
+    argLabel: "<definition>",
+    command: "deepline monitors check"
+  });
+  const payload = await http.request(
+    "/api/v2/monitors/check",
+    { method: "POST", body, ...FORBIDDEN_AS_API_ERROR }
+  );
   printCommandEnvelope(payload, { json: options.json });
 }
-async function handleDeployedGet(key, options) {
+async function handleMonitorsDeploy(definition, options) {
+  const http = buildHttpClient();
+  const body = resolveMonitorJsonBody({
+    positional: definition,
+    file: options.file,
+    argLabel: "<definition>",
+    command: "deepline monitors deploy"
+  });
+  if (options.dryRun) {
+    const payload2 = await http.request(
+      "/api/v2/monitors/check",
+      { method: "POST", body, ...FORBIDDEN_AS_API_ERROR }
+    );
+    const valid = payload2.valid !== false;
+    printCommandEnvelope(
+      { dry_run: true, ...payload2 },
+      { json: options.json, text: renderMonitorDeployPlan(payload2) }
+    );
+    if (!valid) {
+      process.exitCode = 7;
+    }
+    return;
+  }
+  const payload = await http.request(
+    "/api/v2/monitors/deploy",
+    { method: "POST", body, ...FORBIDDEN_AS_API_ERROR }
+  );
+  printCommandEnvelope(payload, {
+    json: options.json,
+    text: renderMonitorDeployCompletion(payload)
+  });
+}
+async function handleMonitorsGet(key, options) {
   const http = buildHttpClient();
   const payload = await http.request(
     `/api/v2/monitors/deployed/${encodeKey(key)}`,
@@ -21572,10 +22559,58 @@ async function handleDeployedGet(key, options) {
   );
   printCommandEnvelope(payload, { json: options.json });
 }
-async function handleDeployedDelete(key, options) {
+async function confirmMonitorDelete(key, options) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stderr
+  });
+  try {
+    const consequence = options.localOnly ? "This removes the Deepline record only (the upstream provider resource is left in place)." : "This deprovisions the upstream provider resource.";
+    const answer = await rl.question(
+      `Delete monitor "${key}"? ${consequence} [y/N] `
+    );
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+async function handleMonitorsDelete(key, options) {
   const http = buildHttpClient();
   const params = new URLSearchParams();
   if (options.localOnly) params.set("local_only", "true");
+  if (options.dryRun) {
+    params.set("dry_run", "true");
+    const payload2 = await http.request(
+      `/api/v2/monitors/deployed/${encodeKey(key)}?${params.toString()}`,
+      { method: "DELETE", ...FORBIDDEN_AS_API_ERROR }
+    );
+    assertMonitorDryRunAcknowledged(payload2, {
+      command: "deepline monitors delete",
+      mutation: "delete"
+    });
+    printCommandEnvelope(payload2, {
+      json: options.json,
+      text: renderMonitorDeletePlan(payload2, key)
+    });
+    return;
+  }
+  if (!options.yes) {
+    const interactive = process.stdout.isTTY === true && process.stdin.isTTY === true;
+    if (!interactive) {
+      throw monitorDeleteRequiresYesError(key, {
+        localOnly: options.localOnly
+      });
+    }
+    const confirmed = await confirmMonitorDelete(key, {
+      localOnly: options.localOnly
+    });
+    if (!confirmed) {
+      process.stderr.write(`Aborted. Monitor "${key}" was not deleted.
+`);
+      process.exitCode = 2;
+      return;
+    }
+  }
   const query = params.toString();
   const payload = await http.request(
     `/api/v2/monitors/deployed/${encodeKey(key)}${query ? `?${query}` : ""}`,
@@ -21583,17 +22618,37 @@ async function handleDeployedDelete(key, options) {
   );
   printCommandEnvelope(payload, { json: options.json });
 }
-async function handleDeployedUpdate(key, patch, options) {
+async function handleMonitorsUpdate(key, patch, options) {
   const http = buildHttpClient();
-  const body = parseJsonObjectArg(patch, "<patch>");
+  const body = resolveMonitorJsonBody({
+    positional: patch,
+    file: options.file,
+    argLabel: "<patch>",
+    command: `deepline monitors update ${key}`
+  });
   const payload = await http.request(
     `/api/v2/monitors/deployed/${encodeKey(key)}`,
     { method: "PATCH", body, ...FORBIDDEN_AS_API_ERROR }
   );
   printCommandEnvelope(payload, { json: options.json });
 }
-async function handleReactivate(key, options) {
+async function handleMonitorsReactivate(key, options) {
   const http = buildHttpClient();
+  if (options.dryRun) {
+    const payload2 = await http.request(
+      `/api/v2/monitors/deployed/${encodeKey(key)}/reactivate?dry_run=true`,
+      { method: "POST", body: {}, ...FORBIDDEN_AS_API_ERROR }
+    );
+    assertMonitorDryRunAcknowledged(payload2, {
+      command: "deepline monitors reactivate",
+      mutation: "reactivate"
+    });
+    printCommandEnvelope(payload2, {
+      json: options.json,
+      text: renderMonitorReactivatePlan(payload2, key)
+    });
+    return;
+  }
   const payload = await http.request(
     `/api/v2/monitors/deployed/${encodeKey(key)}/reactivate`,
     { method: "POST", body: {}, ...FORBIDDEN_AS_API_ERROR }
@@ -21601,116 +22656,240 @@ async function handleReactivate(key, options) {
   printCommandEnvelope(payload, { json: options.json });
 }
 function registerMonitorsCommands(program) {
-  const monitors = program.command("monitors").description("Discover, deploy, and manage Deepline monitors.").addHelpText(
+  const monitors = program.command("monitors").description("Discover, deploy, and manage Deepline monitors.").showSuggestionAfterError(true).addHelpText(
     "after",
     `
 Notes:
-  Monitors are provider-backed signal feeds that deliver events into your
-  workspace. Access is granted by a Deepline admin via Admin -> Rollouts; until
-  then these commands return a clear monitor_access_required error.
+  Deepline monitors are provider-backed signal feeds: a monitor writes provider
+  events into a Customer DB table; a play reacts to each new row via a
+  sqlListeners trigger \u2014 see \`deepline plays bootstrap monitor-triggered\`.
+  Access is granted by a Deepline admin via Admin -> Rollouts; until then these
+  commands return a clear monitor_access_required error.
+
+Exit codes:
+  0 success; 2 usage/local input; 3 auth or permission; 4 not found;
+  5 server failure; 7 validation failed.
+  \`monitors status\` exits 1 when you lack monitor access (documented contract).
 
 Examples:
-  deepline monitors tools --json
-  deepline monitors check '{"key":"my-monitor","tool":"...","payload":{}}'
-  deepline monitors deploy '{"key":"my-monitor","tool":"...","payload":{}}'
-  deepline monitors deployed --json
-  deepline monitors deployed get my-monitor --json
-  deepline monitors reactivate my-monitor --json
+  deepline monitors status --json
+  deepline monitors available --json          # compact list by default
+  deepline monitors available --full --json   # complete catalog
+  deepline monitors available theirstack.saved_search_webhook --json
+  deepline monitors check '{"key":"my-monitor","tool":"theirstack.saved_search_webhook","payload":{}}'
+  deepline monitors deploy --dry-run --file monitor.json
+  deepline monitors deploy --file monitor.json
+  deepline monitors list --status all --json
+  deepline monitors get my-monitor --json
+  deepline monitors update my-monitor '{"controls":{"enabled":false}}' --json
+  deepline monitors delete my-monitor --dry-run
+  deepline monitors reactivate my-monitor --dry-run
 `
   );
-  monitors.command("tools").description("List or describe the monitor tools available to your org.").addHelpText(
-    "after",
-    `
+  withJsonOption(
+    monitors.command("status").description("Check whether you have access to Deepline monitors.").addHelpText(
+      "after",
+      `
 Notes:
-  Read-only. Filter the catalog with --provider, --tool, --search, or --limit.
-  Pass --tool to describe a single monitor tool.
+  Read-only access check. Requires authentication but NOT monitor access, so it
+  is safe to run first to confirm whether you can use the monitor commands. Exits
+  0 when you have access and 1 when you do not, so agents can branch on it (this
+  exit-1 denial contract predates the typed monitor exit codes and is kept).
 
 Examples:
-  deepline monitors tools
-  deepline monitors tools --provider theirstack --json
-  deepline monitors tools --tool theirstack_jobs --json
+  deepline monitors status
+  deepline monitors status --json
 `
-  ).option("--provider <provider>", "Filter by provider").option("--tool <tool>", "Describe a single monitor tool by id").option("--search <query>", "Search monitor tools by text").option("--limit <n>", "Limit the number of monitor tools returned").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleMonitorsTools);
-  monitors.command("check <definition>").description("Validate a monitor definition without deploying it.").addHelpText(
-    "after",
-    `
+    )
+  ).action(monitorsAction(handleMonitorsStatus));
+  withJsonOption(
+    monitors.command("available [tool-id]").alias("tools").description(
+      "List the monitor types you can deploy, or describe one by tool id."
+    ).addHelpText(
+      "after",
+      `
 Notes:
-  Read-only validation. <definition> is a JSON object with key, tool, payload,
-  and optional controls. Does not deploy or spend credits.
+  Read-only catalog of deployable monitor types. Pass a tool id positionally to
+  describe one (payload schema + output streams). Filter the list with
+  --provider, --search, or --limit. List entries include how many monitors you
+  already have deployed on each tool ("deployed: N") when the server reports it.
+  The list is compact by default (id + name + deployed count); pass --full to
+  get the complete catalog (payload schemas + output streams for every tool).
+  Describing a single tool by id always returns the full contract.
 
 Examples:
-  deepline monitors check '{"key":"my-monitor","tool":"theirstack_jobs","payload":{}}'
+  deepline monitors available
+  deepline monitors available --full --json
+  deepline monitors available --provider theirstack --json
+  deepline monitors available theirstack.saved_search_webhook --json
+  deepline monitors available --search jobs --json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleMonitorsCheck);
-  monitors.command("deploy <definition>").description("Deploy a monitor from a definition.").addHelpText(
-    "after",
-    `
+    ).option("--provider <provider>", "Filter by provider").option(
+      "--tool <tool>",
+      "Describe a single monitor tool by id (same as the positional tool-id)"
+    ).option("--search <query>", "Search monitor tools by text").option("--limit <n>", "Limit the number of monitor tools returned").option(
+      "--full",
+      "Return the complete monitor catalog (payload schemas + output streams). The list is compact by default."
+    ).option("--compact", COMPACT_OPTION_DESCRIPTION)
+  ).action(monitorsAction(handleMonitorsAvailable));
+  withJsonOption(
+    monitors.command("list").description("List the monitors you have deployed.").addHelpText(
+      "after",
+      `
 Notes:
-  Mutates workspace state and may spend Deepline credits. <definition> is a JSON
-  object with key, tool, payload, and optional controls.
+  Read-only. --status filters by monitor status: active (default), disabled, or
+  all. The output echoes the status filter that was applied. --compact returns
+  high-signal fields only.
 
 Examples:
-  deepline monitors deploy '{"key":"my-monitor","tool":"theirstack_jobs","payload":{}}'
+  deepline monitors list
+  deepline monitors list --status all --json
+  deepline monitors list --compact --json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleMonitorsDeploy);
-  monitors.command("reactivate <key>").description("Reactivate a previously disabled deployed monitor.").addHelpText(
-    "after",
-    `
+    ).option(
+      "--status <status>",
+      "Filter by monitor status: active (default), disabled, or all"
+    ).option("--limit <n>", "Limit the number of deployed monitors returned").option("--compact", COMPACT_OPTION_DESCRIPTION)
+  ).action(monitorsAction(handleMonitorsList));
+  withJsonOption(
+    monitors.command("get <key>").description("Show a single deployed monitor by its public key.").addHelpText(
+      "after",
+      `
 Notes:
-  Mutates workspace state and may spend Deepline credits.
+  Read-only.
 
 Examples:
-  deepline monitors reactivate my-monitor --json
+  deepline monitors get my-monitor --json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleReactivate);
-  const deployed = monitors.command("deployed").description("List and manage your deployed monitors.").addHelpText(
-    "after",
-    `
+    )
+  ).action(monitorsAction(handleMonitorsGet));
+  withJsonOption(
+    monitors.command("check [definition]").description("Validate a monitor definition without deploying it.").addHelpText(
+      "after",
+      `
 Notes:
-  With no subcommand, lists deployed monitors. Use get/update/delete to manage a
-  single monitor by its public key.
+  Read-only validation. <definition> is a JSON object with key, tool, payload,
+  and optional controls (Deepline lifecycle metadata, e.g.
+  "controls":{"enabled":false}). Pass it positionally, via --file <path>, or
+  from stdin with --file -. Does not deploy or spend credits.
 
 Examples:
-  deepline monitors deployed --json
-  deepline monitors deployed --status all --json
-  deepline monitors deployed get my-monitor --json
+  deepline monitors check '{"key":"my-monitor","tool":"theirstack.saved_search_webhook","payload":{}}'
+  deepline monitors check --file monitor.json
+  cat monitor.json | deepline monitors check --file -
 `
-  ).option("--status <status>", 'Filter by monitor status (or "all")').option("--limit <n>", "Limit the number of deployed monitors returned").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleDeployedList);
-  deployed.command("get <key>").description("Show a single deployed monitor by its public key.").addHelpText(
-    "after",
-    `
+    ).option(
+      "-f, --file <path>",
+      "Read the definition JSON from a file, or - for stdin"
+    )
+  ).action(monitorsAction(handleMonitorsCheck));
+  withJsonOption(
+    monitors.command("deploy [definition]").description("Deploy a monitor from a definition.").addHelpText(
+      "after",
+      `
 Notes:
-  Read-only.
+  Mutates workspace state and may spend Deepline credits. <definition> is a JSON
+  object with key, tool, payload, and optional controls (e.g.
+  "controls":{"enabled":false}). Pass it positionally, via --file <path>, or
+  from stdin with --file -.
+  --dry-run validates the definition and shows the plan (deploy cost in Deepline
+  credits when the server reports it, plus any existing monitors that may
+  already cover this scope) WITHOUT deploying. Exits 0 when valid, 7 when not.
 
 Examples:
-  deepline monitors deployed get my-monitor --json
+  deepline monitors deploy '{"key":"my-monitor","tool":"theirstack.saved_search_webhook","payload":{}}'
+  deepline monitors deploy --dry-run --file monitor.json
+  deepline monitors deploy --file monitor.json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleDeployedGet);
-  deployed.command("update <key> <patch>").description("Update a deployed monitor by its public key.").addHelpText(
-    "after",
-    `
+    ).option(
+      "-f, --file <path>",
+      "Read the definition JSON from a file, or - for stdin"
+    ).option(
+      "--dry-run",
+      "Validate and show the deploy plan (cost, reuse candidates) without deploying"
+    )
+  ).action(monitorsAction(handleMonitorsDeploy));
+  withJsonOption(
+    monitors.command("update <key> [patch]").description("Update a deployed monitor by its public key.").addHelpText(
+      "after",
+      `
 Notes:
-  Mutates workspace state. <patch> is a JSON object of fields to update.
+  Mutates workspace state. <patch> is a JSON object of fields to update, e.g.
+  '{"controls":{"enabled":false}}' to disable a monitor. Pass it positionally,
+  via --file <path>, or from stdin with --file -.
 
 Examples:
-  deepline monitors deployed update my-monitor '{"controls":{"enabled":false}}' --json
+  deepline monitors update my-monitor '{"controls":{"enabled":false}}' --json
+  deepline monitors update my-monitor --file patch.json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleDeployedUpdate);
-  deployed.command("delete <key>").description("Delete a deployed monitor by its public key.").addHelpText(
-    "after",
-    `
+    ).option(
+      "-f, --file <path>",
+      "Read the patch JSON from a file, or - for stdin"
+    )
+  ).action(monitorsAction(handleMonitorsUpdate));
+  withJsonOption(
+    monitors.command("delete <key>").description("Delete a deployed monitor by its public key.").addHelpText(
+      "after",
+      `
 Notes:
-  Mutates workspace state. By default deprovisions the upstream provider
-  resource; pass --local-only to remove only the Deepline-managed record.
+  DESTRUCTIVE. By default deprovisions the upstream provider resource; pass
+  --local-only to remove only the Deepline-managed record.
+  --dry-run shows the delete plan without deleting anything.
+  Interactive terminals get a y/N confirmation; non-interactive runs (agents,
+  scripts, pipes) must pass --yes.
 
 Examples:
-  deepline monitors deployed delete my-monitor --json
-  deepline monitors deployed delete my-monitor --local-only --json
+  deepline monitors delete my-monitor --dry-run
+  deepline monitors delete my-monitor --yes --json
+  deepline monitors delete my-monitor --local-only --yes --json
 `
-  ).option(
-    "--local-only",
-    "Remove only the Deepline-managed record, leaving the upstream resource"
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleDeployedDelete);
+    ).option(
+      "--local-only",
+      "Remove only the Deepline-managed record, leaving the upstream resource"
+    ).option("--dry-run", "Show the delete plan without deleting anything").option(
+      "--yes",
+      "Skip the confirmation prompt (required non-interactively)"
+    )
+  ).action(monitorsAction(handleMonitorsDelete));
+  withJsonOption(
+    monitors.command("reactivate <key>").description("Reactivate a previously disabled deployed monitor.").addHelpText(
+      "after",
+      `
+Notes:
+  Mutates workspace state and may spend Deepline credits.
+  --dry-run shows the reactivation cost (in Deepline credits) without changing
+  anything.
+
+Examples:
+  deepline monitors reactivate my-monitor --dry-run
+  deepline monitors reactivate my-monitor --json
+`
+    ).option("--dry-run", "Show the reactivation cost without reactivating")
+  ).action(monitorsAction(handleMonitorsReactivate));
+  const deployed = withJsonOption(
+    monitors.command("deployed", { hidden: true }).description("Alias of `monitors list` (plus get/update/delete aliases).").option(
+      "--status <status>",
+      "Filter by monitor status: active (default), disabled, or all"
+    ).option("--limit <n>", "Limit the number of deployed monitors returned").option("--compact", COMPACT_OPTION_DESCRIPTION)
+  ).action(monitorsAction(handleMonitorsList));
+  withJsonOption(
+    deployed.command("get <key>").description("Alias of `monitors get <key>`.")
+  ).action(monitorsAction(handleMonitorsGet));
+  withJsonOption(
+    deployed.command("update <key> [patch]").description("Alias of `monitors update <key>`.").option(
+      "-f, --file <path>",
+      "Read the patch JSON from a file, or - for stdin"
+    )
+  ).action(monitorsAction(handleMonitorsUpdate));
+  withJsonOption(
+    deployed.command("delete <key>").description("Alias of `monitors delete <key>`.").option(
+      "--local-only",
+      "Remove only the Deepline-managed record, leaving the upstream resource"
+    ).option("--dry-run", "Show the delete plan without deleting anything").option(
+      "--yes",
+      "Skip the confirmation prompt (required non-interactively)"
+    )
+  ).action(monitorsAction(handleMonitorsDelete));
 }
 
 // src/cli/commands/org.ts
@@ -22735,7 +23914,7 @@ Examples:
 }
 
 // src/cli/commands/switch.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync7, readFileSync as readFileSync9, writeFileSync as writeFileSync11 } from "fs";
+import { existsSync as existsSync9, mkdirSync as mkdirSync7, readFileSync as readFileSync10, writeFileSync as writeFileSync11 } from "fs";
 import { homedir as homedir9 } from "os";
 import { dirname as dirname9, join as join9 } from "path";
 function hostSlugFromBaseUrl(baseUrl) {
@@ -22770,7 +23949,7 @@ function activeFamilyPath() {
 function readActiveFamily() {
   const path = activeFamilyPath();
   try {
-    return readFileSync9(path, "utf-8").trim() || "sdk";
+    return readFileSync10(path, "utf-8").trim() || "sdk";
   } catch {
     return "sdk";
   }
@@ -22899,7 +24078,7 @@ import {
   chmodSync,
   existsSync as existsSync10,
   mkdtempSync,
-  readFileSync as readFileSync10,
+  readFileSync as readFileSync11,
   writeFileSync as writeFileSync13
 } from "fs";
 import { tmpdir as tmpdir3 } from "os";
@@ -24302,7 +25481,7 @@ function readJsonArgument(raw, flagName) {
     throw new Error(`Invalid ${flagName} value: empty @file path.`);
   }
   try {
-    return readFileSync10(resolveAtFilePath(filePath), "utf8").replace(
+    return readFileSync11(resolveAtFilePath(filePath), "utf8").replace(
       /^\uFEFF/,
       ""
     );
@@ -24972,9 +26151,10 @@ var PLAY_EQUIVALENT = {
   delete: "deepline plays delete <name>"
 };
 var MIGRATE_HINT = "deepline workflows transform <id>";
-var JSON_OPTION_DESCRIPTION = "Emit JSON output. Also automatic when stdout is piped";
-function withJsonOption(command) {
-  return command.option("--json", JSON_OPTION_DESCRIPTION);
+var TRIGGER_REDIRECT = "Looking to trigger a play automatically? Use a trigger binding in definePlay \u2014 `cron`/`webhook`, or `sqlListeners` to run on a monitor\u2019s output (see `deepline monitors available <id>` for a monitor\u2019s streams and the deepline-monitors skill). `workflows` only manages prebuilt plays and is deprecated in favor of `plays`.";
+var JSON_OPTION_DESCRIPTION2 = "Emit JSON output. Also automatic when stdout is piped";
+function withJsonOption2(command) {
+  return command.option("--json", JSON_OPTION_DESCRIPTION2);
 }
 var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set([
   "completed",
@@ -24999,6 +26179,7 @@ function noticeToStderr(command) {
     `note: \`deepline workflows ${command}\` is a legacy surface \u2014 workflows are becoming plays.
       equivalent: \`${deprecation.use}\`
       migrate this workflow: \`${MIGRATE_HINT}\`
+      ${TRIGGER_REDIRECT}
 `
   );
 }
@@ -25232,7 +26413,7 @@ async function handleTail(id, runId, options) {
 }
 function registerWorkflowCommands(program) {
   const workflows = program.command("workflows").description(
-    "Legacy cloud workflows (now becoming plays). Commands still work; use `workflows transform` to migrate one to a play."
+    "Legacy cloud workflows (now becoming plays). Commands still work; use `workflows transform` to migrate one to a play. " + TRIGGER_REDIRECT
   ).addHelpText(
     "after",
     `
@@ -25244,9 +26425,13 @@ keep working, but new work belongs in plays. Migrate a workflow with:
 
 Equivalents: list\u2192plays list \xB7 call\u2192plays run \xB7 apply\u2192plays publish \xB7
 lint\u2192plays check \xB7 runs\u2192runs list.
+
+${TRIGGER_REDIRECT}
+Add the binding as the third arg to definePlay in your .play.ts; the
+deepline-monitors skill has a monitor-triggered example.
 `
   );
-  withJsonOption(
+  withJsonOption2(
     workflows.command("transform [id]").description("Compile a workflow into a reviewable V2 play (.play.ts).").option("--all", "Transform every workflow in the workspace").option("--out <dir>", "Output directory for generated plays", "./plays").option("--publish", "Publish each clean play immediately")
   ).addHelpText(
     "after",
@@ -25263,48 +26448,48 @@ Notes:
   ).action(async (id, options) => {
     process.exitCode = await handleTransform(id, options);
   });
-  withJsonOption(
+  withJsonOption2(
     workflows.command("list").description("List workspace workflows.").option("--limit <n>", "Max workflows to return")
   ).action(handleList2);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("get <id>").description(
       "Fetch a workflow, including its published-revision config."
     )
   ).action(handleGet);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("disable <id>").description("Turn a workflow off.")
   ).action(handleDisable);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("enable <id>").description("Turn a workflow back on.")
   ).action(handleEnable);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("delete <id>").description("Delete a workflow and its revisions/runs.")
   ).action(handleDelete);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("apply").description("Create or update a workflow from config.").option("--payload <json>", "Inline config JSON").option("--file <path>", "Path to a config JSON file")
   ).action(handleApply);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("lint").description("Validate a workflow config without saving.").option("--payload <json>", "Inline config JSON").option("--file <path>", "Path to a config JSON file")
   ).action(handleLint);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("schema").description("Fetch live workflow request schemas.").option(
       "--subject <subject>",
       "Schema subject (apply|call|trigger|all|\u2026)"
     )
   ).action(handleSchema);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("call").description("Queue a workflow run.").option("--workflow-id <id>", "Workflow id").option("--workflow-name <name>", "Workflow name").option("--payload <json>", "Run input JSON").option("--mode <mode>", "live | dry_run | smoke_test")
   ).action(handleCall);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("runs <id>").description("List a workflow\u2019s runs.").option("--limit <n>", "Max runs to return")
   ).action(handleRuns);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("run <id> <runId>").description("Fetch a single workflow run.")
   ).action(handleRun);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("tail <id> <runId>").description("Poll a workflow run until it reaches a terminal status.").option("--interval-ms <n>", "Poll interval in ms (default 2000)")
   ).action(handleTail);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("cancel <id> <runId>").description("Cancel a running workflow run.")
   ).action(handleCancel);
 }
@@ -25315,7 +26500,7 @@ import {
   existsSync as existsSync12,
   mkdirSync as mkdirSync10,
   realpathSync as realpathSync3,
-  readFileSync as readFileSync12,
+  readFileSync as readFileSync13,
   renameSync,
   rmSync as rmSync4,
   unlinkSync,
@@ -25326,7 +26511,7 @@ 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 readFileSync11, writeFileSync as writeFileSync14 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync9, readFileSync as readFileSync12, writeFileSync as writeFileSync14 } from "fs";
 import { dirname as dirname12, join as join13 } from "path";
 
 // ../shared_libs/cli/install-commands.json
@@ -25455,7 +26640,7 @@ function readPluginSkillsVersion() {
   const dir = activePluginSkillsDir();
   if (!dir) return "";
   try {
-    return readFileSync11(join13(dir, ".version"), "utf-8").trim();
+    return readFileSync12(join13(dir, ".version"), "utf-8").trim();
   } catch {
     return "";
   }
@@ -25472,7 +26657,7 @@ function readSdkSkillsLocalVersion(baseUrl) {
   const path = existsSync11(sdkSkillsVersionPath(baseUrl)) ? sdkSkillsVersionPath(baseUrl) : legacySdkSkillsVersionPath(baseUrl);
   if (!existsSync11(path)) return "";
   try {
-    return readFileSync11(path, "utf-8").trim();
+    return readFileSync12(path, "utf-8").trim();
   } catch {
     return "";
   }
@@ -25767,7 +26952,7 @@ function sidecarStateDir(input2) {
 }
 function readOptionalText(path) {
   try {
-    return readFileSync12(path, "utf8").trim();
+    return readFileSync13(path, "utf8").trim();
   } catch {
     return "";
   }
@@ -25902,7 +27087,7 @@ function readAutoUpdateFailure(plan) {
   if (!path) return null;
   try {
     const parsed = JSON.parse(
-      readFileSync12(path, "utf8")
+      readFileSync13(path, "utf8")
     );
     if ((parsed.kind === "npm-global" || parsed.kind === "python-sidecar") && typeof parsed.packageSpec === "string" && typeof parsed.failedAt === "string" && typeof parsed.exitCode === "number" && typeof parsed.manualCommand === "string") {
       return parsed;
@@ -25986,7 +27171,7 @@ function installedPackageVersion(versionDir) {
     "package.json"
   );
   try {
-    const parsed = JSON.parse(readFileSync12(packageJsonPath, "utf8"));
+    const parsed = JSON.parse(readFileSync13(packageJsonPath, "utf8"));
     return typeof parsed.version === "string" ? safeVersionSegment(parsed.version) : "";
   } catch {
     return "";