deepline 0.3.99 → 0.3.101

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

@@ -1091,7 +1091,10 @@ export type MonitorBatchExistingSubmitOptions = {
   kind: 'audit' | 'deactivate' | 'reactivate' | 'repair';
   scope: MonitorBatchScope;
   dryRun?: boolean;
-  /** Required for deactivate; it is the declared reason shown by health/UI. */
+  /**
+   * A declared policy reason for target deactivation. Omit it for an explicit
+   * customer-owned key teardown; absent is the durable customer intent.
+   */
   deactivationReason?: string;
   /** Stable retry key. Reusing it joins the original durable operation. */
   idempotencyKey: string;

package/dist/bundling-sources/sdk/src/plays/bundle-play-file.ts

@@ -5,6 +5,7 @@ import { existsSync } from 'node:fs';
 import { realpath } from 'node:fs/promises';
 import {
   bundlePlayFile as bundlePlayFileCore,
+  PLAY_BUNDLE_CACHE_NAMESPACE,
   type BundlePlayFileOptions,
   type BundledPlayFileSuccess,
   type BundledPlayFileResult,
@@ -40,7 +41,6 @@ export type {
 
 export { extractDefinedPlayName } from '../../../shared_libs/plays/bundling/index.js';
 
-const PLAY_BUNDLE_CACHE_VERSION = 37;
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const SDK_PACKAGE_ROOT = resolve(MODULE_DIR, '..', '..');
 const SOURCE_REPO_ROOT = resolve(SDK_PACKAGE_ROOT, '..', '..');
@@ -126,10 +126,7 @@ export function createSdkPlayBundlingAdapter(): PlayBundlingAdapter {
     nodeModulesDir: HAS_PACKAGED_BUNDLING_SOURCES
       ? resolve(SDK_PACKAGE_ROOT, 'node_modules')
       : resolve(PROJECT_ROOT, 'node_modules'),
-    cacheDir: join(
-      tmpdir(),
-      `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`,
-    ),
+    cacheDir: join(tmpdir(), PLAY_BUNDLE_CACHE_NAMESPACE),
     sdkSourceRoot: SDK_SOURCE_ROOT,
     sdkPackageJson: SDK_PACKAGE_JSON,
     sdkEntryFile: SDK_ENTRY_FILE,

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

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.99',
+  version: '0.3.101',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/shared_libs/monitors/provider-monitor-batch-operation.ts

@@ -78,7 +78,11 @@ export type ProviderMonitorBatchOperationRequest = {
    * this origin instead of recomputing it from a later deployment.
    */
   callbackBaseUrl?: string;
-  /** Required for direct/target deactivation; Fleet teardown may be customer-owned. */
+  /**
+   * A closed, platform-owned reason for a policy teardown. Omit it for a
+   * customer-owned exact-key or Fleet teardown: absence is the durable
+   * representation of the customer's own inactive intent.
+   */
   deactivationReason?: string;
 };
 
@@ -204,13 +208,11 @@ export function validateProviderMonitorBatchOperationRequest(
     if (request.kind === 'converge') {
       throw new Error('Batch converge requires exactly one Fleet scope.');
     }
-    if (request.kind === 'deactivate' && !request.deactivationReason) {
-      throw new Error(
-        'Batch deactivate requires a declared deactivation reason.',
-      );
-    }
-    if (request.kind === 'deactivate') {
-      requireMonitorDeactivationReason(request.deactivationReason!);
+    if (
+      request.kind === 'deactivate' &&
+      request.deactivationReason !== undefined
+    ) {
+      requireMonitorDeactivationReason(request.deactivationReason);
     }
     return {
       ...request,

package/dist/bundling-sources/shared_libs/plays/bundling/index.ts

@@ -59,15 +59,11 @@ import { validatePlaySourceFilesHaveNoInlineSecrets } from '../secret-guardrails
 import { MAX_PLAY_BUNDLE_BYTES } from './limits';
 import { PLAY_AUTHORING_CONTRACT_EDITION } from '../authoring-contract';
 
-// The authored tool-error schema and the authored docflow block are both part
-// of the artifact bytes. Do not reuse a local bundle cached before either
-// compatibility selection or docflow instrumentation entered graph analysis.
-// Keep this aligned with the app and SDK adapters' cache namespace.
-const PLAY_BUNDLE_CACHE_VERSION = 37;
-const PLAY_ARTIFACT_CACHE_DIR = join(
-  tmpdir(),
-  `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`,
-);
+// Local bundle caches may be discarded when compiler-only analysis changes;
+// this descriptive namespace is not a runtime wire or schema version.
+export const PLAY_BUNDLE_CACHE_NAMESPACE =
+  'deepline-play-artifacts-docflow-jsdoc';
+const PLAY_ARTIFACT_CACHE_DIR = join(tmpdir(), PLAY_BUNDLE_CACHE_NAMESPACE);
 const PLAY_PROXY_NAMESPACE = 'deepline-play-runtime-ref';
 const SOURCE_EXTENSIONS = [
   '.ts',

package/dist/bundling-sources/shared_libs/plays/bundling/repository-adapter.ts

@@ -1,6 +1,6 @@
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
-import type { PlayBundlingAdapter } from './index';
+import { PLAY_BUNDLE_CACHE_NAMESPACE, type PlayBundlingAdapter } from './index';
 import { discoverPackagedLocalFiles } from '../local-file-discovery';
 
 /** Repository source bundling shared by the API and the deploy worker.
@@ -15,7 +15,7 @@ export function createRepositoryPlayBundlingAdapter(options: {
     projectRoot: options.projectRoot,
     sourceIdentityRoot: options.sourceIdentityRoot,
     nodeModulesDir: resolve(options.projectRoot, 'node_modules'),
-    cacheDir: join(tmpdir(), 'deepline-play-artifacts-v37'),
+    cacheDir: join(tmpdir(), PLAY_BUNDLE_CACHE_NAMESPACE),
     sdkSourceRoot,
     sdkPackageJson: resolve(sdkSourceRoot, '..', 'package.json'),
     sdkEntryFile: resolve(sdkSourceRoot, 'index.ts'),

package/dist/bundling-sources/shared_libs/plays/deploy/control-plane-types.ts

@@ -44,6 +44,7 @@ export type PlayProjectDoc = {
   productionBranch: string;
   checkOnPullRequest: boolean;
   disabledAt?: number;
+  unlinkedAt?: number;
   createdByUserId: string;
   createdAt: number;
   updatedAt: number;

package/dist/bundling-sources/shared_libs/plays/docflow.ts

@@ -617,7 +617,7 @@ function levenshtein(left: string, right: string): number {
   return row[right.length]!;
 }
 
-const MERMAID_BLOCK = /\/\*\*\s*@mermaid(?:\s|\r?\n)([\s\S]*?)\*\//g;
+const JSDOC_BLOCK = /\/\*\*([\s\S]*?)\*\//g;
 /**
  * What a block header may name: an export name, or the play's own kebab-case
  * name. Hyphens are in the set for the second — `@mermaid name-to-linkedin-url-
@@ -935,9 +935,12 @@ export function parsePlayDocflowFile(
     syntax: NonNullable<PlayDocflow['syntax']>;
     body: string;
   }> = [];
-  MERMAID_BLOCK.lastIndex = 0;
-  for (const match of sourceCode.matchAll(MERMAID_BLOCK)) {
-    rawBlocks.push({ syntax: 'mermaid', body: cleanBlockBody(match[1]!) });
+  JSDOC_BLOCK.lastIndex = 0;
+  for (const match of sourceCode.matchAll(JSDOC_BLOCK)) {
+    const cleanedBody = cleanBlockBody(match[1]!);
+    const mermaid = /^@mermaid(?:[ \t]+|\r?\n|$)([\s\S]*)$/.exec(cleanedBody);
+    if (!mermaid) continue;
+    rawBlocks.push({ syntax: 'mermaid', body: mermaid[1]!.trim() });
   }
   if (rawBlocks.length === 0) return { blocks: [], bindings: [], errors };
 

package/dist/bundling-sources/shared_libs/security/secret-redaction.ts

@@ -2,6 +2,10 @@ const REDACTED_VALUE = '[REDACTED]';
 
 type SecretRedactionOptions = {
   redactHighEntropy?: boolean;
+  /** Preserve only known pagination cursor fields in authenticated result data. */
+  keyPolicy?: 'strict' | 'public-result';
+  /** Replace sample cursor values with a non-capability-bearing placeholder. */
+  placeholderContinuationValues?: boolean;
 };
 
 const SENSITIVE_KEY_PATTERNS = [
@@ -16,6 +20,55 @@ const SENSITIVE_KEY_PATTERNS = [
   /private/i,
 ];
 
+const PUBLIC_RESULT_CURSOR_KEYS = new Set([
+  'cursor',
+  'encoded_cursor',
+  'encodedCursor',
+  'next_cursor',
+  'nextCursor',
+  'scroll_token',
+  'scrollToken',
+  'pagination_token',
+  'paginationToken',
+  'continuation_token',
+  'continuationToken',
+  'page_token',
+  'pageToken',
+  'next_page_token',
+  'nextPageToken',
+  'previous_page_token',
+  'previousPageToken',
+  'prev_page_token',
+  'prevPageToken',
+  'next_token',
+  'nextToken',
+  'offset_token',
+  'offsetToken',
+]);
+
+const PUBLIC_RESULT_TOKEN_EXPIRY_KEYS = new Set([
+  'page_token_expiry',
+  'pageTokenExpiry',
+]);
+
+const PUBLIC_RESULT_TOKEN_COUNT_KEYS = new Set([
+  'input_tokens',
+  'inputTokens',
+  'output_tokens',
+  'outputTokens',
+  'total_tokens',
+  'totalTokens',
+  'tokens_used',
+  'tokensUsed',
+]);
+
+const PAGINATION_CONTAINER_KEYS = new Set([
+  'pagination',
+  'paging',
+  'page_info',
+  'pageInfo',
+]);
+
 const SAFE_IDENTIFIER_KEYS = new Set([
   'artifactHash',
   'artifactHashes',
@@ -135,6 +188,39 @@ function shouldRedactKey(key: string) {
   return SENSITIVE_KEY_PATTERNS.some((pattern) => pattern.test(key));
 }
 
+function isPublicResultCursorKey(
+  key: string,
+  path: readonly string[],
+): boolean {
+  return (
+    PUBLIC_RESULT_CURSOR_KEYS.has(key) ||
+    (key === 'token' && PAGINATION_CONTAINER_KEYS.has(path.at(-1) ?? ''))
+  );
+}
+
+function isPublicResultSafeTokenKey(
+  key: string,
+  path: readonly string[],
+  value: unknown,
+): boolean {
+  if (isPublicResultCursorKey(key, path)) return true;
+  if (value === null) {
+    return (
+      PUBLIC_RESULT_TOKEN_EXPIRY_KEYS.has(key) ||
+      PUBLIC_RESULT_TOKEN_COUNT_KEYS.has(key)
+    );
+  }
+  if (PUBLIC_RESULT_TOKEN_COUNT_KEYS.has(key)) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+  }
+  return (
+    PUBLIC_RESULT_TOKEN_EXPIRY_KEYS.has(key) &&
+    typeof value === 'string' &&
+    /^\d{4}-\d{2}-\d{2}T/.test(value) &&
+    Number.isFinite(Date.parse(value))
+  );
+}
+
 function maybeRedactString(value: string, options: SecretRedactionOptions) {
   if (EXPLICIT_SECRET_VALUE_PATTERNS.some((pattern) => pattern.test(value))) {
     return REDACTED_VALUE;
@@ -171,6 +257,21 @@ export function redactSecretsInValue<T>(
     if (parentKey && SAFE_IDENTIFIER_KEYS.has(parentKey)) {
       return value as T;
     }
+    if (
+      parentKey &&
+      options.keyPolicy === 'public-result' &&
+      isPublicResultSafeTokenKey(parentKey, [], value)
+    ) {
+      const redacted = maybeRedactString(value, options);
+      return (
+        options.placeholderContinuationValues &&
+        isPublicResultCursorKey(parentKey, []) &&
+        redacted !== REDACTED_VALUE &&
+        redacted.length > 0
+          ? '[PAGINATION_CURSOR]'
+          : redacted
+      ) as T;
+    }
     if (parentKey && shouldRedactKey(parentKey)) {
       return REDACTED_VALUE as T;
     }
@@ -185,7 +286,8 @@ export function redactSecretsInValue<T>(
     source: Container;
     target: Container;
     parentKey?: string;
-  }> = [{ source: value as Container, target: root, parentKey }];
+    path: string[];
+  }> = [{ source: value as Container, target: root, parentKey, path: [] }];
 
   const redactNestedValue = (
     item: unknown,
@@ -196,7 +298,9 @@ export function redactSecretsInValue<T>(
       return REDACTED_VALUE;
     }
     if (itemParentKey && SAFE_IDENTIFIER_KEYS.has(itemParentKey)) return item;
-    if (itemParentKey && shouldRedactKey(itemParentKey)) return REDACTED_VALUE;
+    if (itemParentKey && shouldRedactKey(itemParentKey)) {
+      return REDACTED_VALUE;
+    }
     return maybeRedactString(item, options);
   };
 
@@ -206,6 +310,24 @@ export function redactSecretsInValue<T>(
     const sourceIsArray = Array.isArray(current.source);
     for (const [key, item] of Object.entries(current.source)) {
       const itemParentKey = sourceIsArray ? current.parentKey : key;
+      if (
+        !sourceIsArray &&
+        options.keyPolicy === 'public-result' &&
+        isPublicResultSafeTokenKey(key, current.path, item) &&
+        (!item || typeof item !== 'object')
+      ) {
+        const redacted =
+          typeof item === 'string' ? maybeRedactString(item, options) : item;
+        (current.target as Record<string, unknown>)[key] =
+          options.placeholderContinuationValues &&
+          isPublicResultCursorKey(key, current.path) &&
+          typeof redacted === 'string' &&
+          redacted !== REDACTED_VALUE &&
+          redacted.length > 0
+            ? '[PAGINATION_CURSOR]'
+            : redacted;
+        continue;
+      }
       if (!sourceIsArray && shouldRedactKey(key)) {
         (current.target as Record<string, unknown>)[key] = REDACTED_VALUE;
         continue;
@@ -217,6 +339,7 @@ export function redactSecretsInValue<T>(
           source: item as Container,
           target: nestedTarget,
           parentKey: itemParentKey,
+          path: sourceIsArray ? current.path : [...current.path, key],
         });
         continue;
       }
@@ -242,6 +365,18 @@ export function redactSecretsInCustomerValue<T>(
   return redactSecretsInValue(value, parentKey, { redactHighEntropy: false });
 }
 
+/** Redaction for authenticated successful provider or Play result data. */
+export function redactSecretsInPublicResultValue<T>(
+  value: T,
+  options: { placeholderContinuationValues?: boolean } = {},
+): T {
+  return redactSecretsInValue(value, undefined, {
+    redactHighEntropy: false,
+    keyPolicy: 'public-result',
+    placeholderContinuationValues: options.placeholderContinuationValues,
+  });
+}
+
 export function redactSecretsInJsonText(
   text: string,
   options: SecretRedactionOptions = {},
@@ -265,3 +400,11 @@ export function redactSecretsInJsonText(
 export function redactSecretsInCustomerJsonText(text: string) {
   return redactSecretsInJsonText(text, { redactHighEntropy: false });
 }
+
+/** Redaction for serialized authenticated provider or Play result data. */
+export function redactSecretsInPublicResultJsonText(text: string) {
+  return redactSecretsInJsonText(text, {
+    redactHighEntropy: false,
+    keyPolicy: 'public-result',
+  });
+}

package/dist/cli/index.js

@@ -1298,7 +1298,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.99",
+  version: "0.3.101",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -9780,7 +9780,10 @@ Examples:
   deepline auth register --wait no
   deepline auth register --auth-scope folder --wait no
 `
-  ).option("--org-name <name>", "Workspace name to prefill").option(
+  ).option(
+    "--org-name <name>",
+    "Use this workspace, or create a separate one with this name"
+  ).option(
     "--org-id <id>",
     "Bind to this workspace directly, skipping the browser picker"
   ).option("--agent-name <name>", "Agent name to register").option("--wait <mode>", "Wait mode: auto, yes, or no", "auto").option("--no-wait", "Alias for --wait no").option(
@@ -10180,7 +10183,7 @@ async function handleUsage(options) {
     `Balance: ${payload.balance ?? "(unknown)"}`,
     `Last 30 days usage: ${last30Usage ?? "(unknown)"}`,
     ...Number.isFinite(temporaryHolds) && temporaryHolds > 0 ? [`Temporary holds: ${temporaryHolds}`] : [],
-    `Monthly spend guidance: ${quota.enabled ? quota.monthly_credits_limit ?? "(unknown)" : "off"}`,
+    `Monthly usage cap: ${quota.enabled ? quota.monthly_credits_limit ?? "(unknown)" : "off"}`,
     ...options.runId && recent.run_id ? [
       `Run spend: ${(payload.run ?? {}).spent_credits ?? "(unknown)"} Deepline Credits`
     ] : [],
@@ -10212,9 +10215,9 @@ async function handleLimit(options) {
     "/api/v2/billing/limit"
   );
   const lines = payload.enabled ? [
-    `Monthly spend guidance: ${payload.monthly_credits_limit ?? "(unknown)"}`,
-    "Enforcement: advisory; available balance remains the exact admission control."
-  ] : ["Monthly spend guidance: off"];
+    `Monthly usage cap: ${payload.monthly_credits_limit ?? "(unknown)"}`,
+    "Enforcement: checked before new calls; in-flight work can exceed the cap."
+  ] : ["Monthly usage cap: off"];
   printCommandEnvelope(
     {
       ...payload,
@@ -10236,7 +10239,7 @@ async function handleSetLimit(credits, options) {
         sections: [
           {
             title: "billing limit",
-            lines: [`Monthly spend guidance set to ${credits} credits.`]
+            lines: [`Monthly usage cap set to ${credits} credits.`]
           }
         ]
       }
@@ -10256,7 +10259,7 @@ async function handleLimitOff(options) {
         sections: [
           {
             title: "billing limit",
-            lines: ["Monthly spend guidance is now off."]
+            lines: ["Monthly usage cap is now off."]
           }
         ]
       }
@@ -11097,36 +11100,36 @@ Examples:
     "--cursor <cursor>",
     "Recent-call cursor from the previous response"
   ).option("--run-id <run_id>", "Show recent usage for one play run").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleUsage);
-  billing.command("limit").description("Show configured monthly spend guidance.").addHelpText(
+  billing.command("limit").description("Show configured monthly usage cap.").addHelpText(
     "after",
     `
 Notes:
-  Read-only. Shows whether monthly workspace spend guidance is enabled.
-  Guidance does not reject funded work; available balance remains exact.
+  Read-only. Shows whether monthly workspace usage cap is enabled.
+  New calls are checked against this usage cap, separately from wallet funding.
 
 Examples:
   deepline billing limit
   deepline billing limit --json
 `
   ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleLimit);
-  billing.command("set-limit").description("Set monthly spend guidance.").addHelpText(
+  billing.command("set-limit").description("Set monthly usage cap.").addHelpText(
     "after",
     `
 Notes:
   Mutates workspace billing settings. The argument is a Deepline credit amount,
-  not dollars and not provider credits. Guidance is advisory; it does not
-  replace the exact available-balance admission check.
+  not dollars and not provider credits. New calls are checked against the cap;
+  in-flight work can still finish and exceed it. Buying credits does not reset it.
 
 Examples:
   deepline billing set-limit 500
   deepline billing set-limit 500 --json
 `
   ).argument("<credits>", "Monthly credits limit").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleSetLimit);
-  billing.command("off").description("Disable monthly spend guidance.").addHelpText(
+  billing.command("off").description("Disable monthly usage cap.").addHelpText(
     "after",
     `
 Notes:
-  Mutates workspace billing settings by removing monthly Deepline spend guidance.
+  Mutates workspace billing settings by removing monthly Deepline usage cap.
 
 Examples:
   deepline billing off
@@ -16555,11 +16558,8 @@ function collectInlineSecretFindings(sourceCode) {
 var MAX_PLAY_BUNDLE_BYTES = 30 * 1024 * 1024;
 
 // ../plays/bundling/index.ts
-var PLAY_BUNDLE_CACHE_VERSION = 37;
-var PLAY_ARTIFACT_CACHE_DIR = (0, import_node_path11.join)(
-  (0, import_node_os7.tmpdir)(),
-  `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`
-);
+var PLAY_BUNDLE_CACHE_NAMESPACE = "deepline-play-artifacts-docflow-jsdoc";
+var PLAY_ARTIFACT_CACHE_DIR = (0, import_node_path11.join)((0, import_node_os7.tmpdir)(), PLAY_BUNDLE_CACHE_NAMESPACE);
 var NODE_BUILTIN_SET = new Set(
   import_node_module.builtinModules.flatMap(
     (name) => name.startsWith("node:") ? [name, name.slice(5)] : [name, `node:${name}`]
@@ -35399,6 +35399,28 @@ function monitorBatchScope(options, kind) {
 function monitorBatchIdempotencyKey(kind, value) {
   return value?.trim() || `monitor-batch-${kind}-${(0, import_node_crypto8.randomUUID)()}`;
 }
+function legacyDryRunManifest(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+  const object = asRecord2(parsed);
+  if (object && asString(object.key) && asString(object.tool)) {
+    return raw;
+  }
+  const isBatchDocument = Array.isArray(parsed) || object !== null && (Object.prototype.hasOwnProperty.call(object, "monitors") || object.kind === "batch");
+  if (!isBatchDocument) return raw;
+  const lint = lintMonitorBatchInput(parsed);
+  if (!lint.normalized) {
+    throw new MonitorsUsageError(
+      lint.issues.filter((issue) => issue.severity === "error").map((issue) => `${issue.path || "batch"}: ${issue.message}`).join("; ")
+    );
+  }
+  return `${lint.normalized.monitors.map((monitor) => JSON.stringify(monitor)).join("\n")}
+`;
+}
 async function handleMonitorBatchDeploy(options) {
   if (!options.file?.trim()) {
     throw new MonitorsUsageError(
@@ -35421,6 +35443,9 @@ async function handleMonitorBatchDeploy(options) {
   if (!manifestNdjson.trim()) {
     throw new MonitorsUsageError("Monitor batch manifest is empty.");
   }
+  if (options.dryRun === true) {
+    manifestNdjson = legacyDryRunManifest(manifestNdjson);
+  }
   const idempotencyKey = monitorBatchIdempotencyKey(
     "deploy",
     options.idempotencyKey
@@ -35450,9 +35475,10 @@ async function handleMonitorBatch(kind, options) {
       `monitors batch ${kind} changes provider monitors asynchronously. Preview with --dry-run, then confirm with --yes.`
     );
   }
-  if (kind === "deactivate" && !options.reason?.trim()) {
+  const scope = monitorBatchScope(options, kind);
+  if (kind === "deactivate" && scope.kind === "target" && !options.reason?.trim()) {
     throw new MonitorsUsageError(
-      "monitors batch deactivate requires --reason (for example insufficient_balance or billing_failure)."
+      "monitors batch deactivate --target requires --reason (for example insufficient_balance or billing_failure). Omit --reason with --keys for a customer-requested teardown."
     );
   }
   const idempotencyKey = monitorBatchIdempotencyKey(
@@ -35461,7 +35487,7 @@ async function handleMonitorBatch(kind, options) {
   );
   const result = await new DeeplineClient().monitors.batch.submit({
     kind,
-    scope: monitorBatchScope(options, kind),
+    scope,
     dryRun: options.dryRun === true,
     ...options.reason?.trim() ? { deactivationReason: options.reason.trim() } : {},
     idempotencyKey
@@ -35666,7 +35692,10 @@ Examples:
       batch.command("deactivate").description(
         "Durably deactivate a selection through provider batch deletes."
       )
-    ).requiredOption("--reason <reason>", "Declared deactivation reason").option("--yes", "Confirm the asynchronous provider deactivation")
+    ).option(
+      "--reason <reason>",
+      "Declared policy reason; required with --target and omitted for a customer-requested --keys teardown"
+    ).option("--yes", "Confirm the asynchronous provider deactivation")
   ).action(
     monitorsAction(
       (options) => handleMonitorBatch("deactivate", options)

package/dist/cli/index.mjs

@@ -1271,7 +1271,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.99",
+  version: "0.3.101",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -9765,7 +9765,10 @@ Examples:
   deepline auth register --wait no
   deepline auth register --auth-scope folder --wait no
 `
-  ).option("--org-name <name>", "Workspace name to prefill").option(
+  ).option(
+    "--org-name <name>",
+    "Use this workspace, or create a separate one with this name"
+  ).option(
     "--org-id <id>",
     "Bind to this workspace directly, skipping the browser picker"
   ).option("--agent-name <name>", "Agent name to register").option("--wait <mode>", "Wait mode: auto, yes, or no", "auto").option("--no-wait", "Alias for --wait no").option(
@@ -10165,7 +10168,7 @@ async function handleUsage(options) {
     `Balance: ${payload.balance ?? "(unknown)"}`,
     `Last 30 days usage: ${last30Usage ?? "(unknown)"}`,
     ...Number.isFinite(temporaryHolds) && temporaryHolds > 0 ? [`Temporary holds: ${temporaryHolds}`] : [],
-    `Monthly spend guidance: ${quota.enabled ? quota.monthly_credits_limit ?? "(unknown)" : "off"}`,
+    `Monthly usage cap: ${quota.enabled ? quota.monthly_credits_limit ?? "(unknown)" : "off"}`,
     ...options.runId && recent.run_id ? [
       `Run spend: ${(payload.run ?? {}).spent_credits ?? "(unknown)"} Deepline Credits`
     ] : [],
@@ -10197,9 +10200,9 @@ async function handleLimit(options) {
     "/api/v2/billing/limit"
   );
   const lines = payload.enabled ? [
-    `Monthly spend guidance: ${payload.monthly_credits_limit ?? "(unknown)"}`,
-    "Enforcement: advisory; available balance remains the exact admission control."
-  ] : ["Monthly spend guidance: off"];
+    `Monthly usage cap: ${payload.monthly_credits_limit ?? "(unknown)"}`,
+    "Enforcement: checked before new calls; in-flight work can exceed the cap."
+  ] : ["Monthly usage cap: off"];
   printCommandEnvelope(
     {
       ...payload,
@@ -10221,7 +10224,7 @@ async function handleSetLimit(credits, options) {
         sections: [
           {
             title: "billing limit",
-            lines: [`Monthly spend guidance set to ${credits} credits.`]
+            lines: [`Monthly usage cap set to ${credits} credits.`]
           }
         ]
       }
@@ -10241,7 +10244,7 @@ async function handleLimitOff(options) {
         sections: [
           {
             title: "billing limit",
-            lines: ["Monthly spend guidance is now off."]
+            lines: ["Monthly usage cap is now off."]
           }
         ]
       }
@@ -11082,36 +11085,36 @@ Examples:
     "--cursor <cursor>",
     "Recent-call cursor from the previous response"
   ).option("--run-id <run_id>", "Show recent usage for one play run").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleUsage);
-  billing.command("limit").description("Show configured monthly spend guidance.").addHelpText(
+  billing.command("limit").description("Show configured monthly usage cap.").addHelpText(
     "after",
     `
 Notes:
-  Read-only. Shows whether monthly workspace spend guidance is enabled.
-  Guidance does not reject funded work; available balance remains exact.
+  Read-only. Shows whether monthly workspace usage cap is enabled.
+  New calls are checked against this usage cap, separately from wallet funding.
 
 Examples:
   deepline billing limit
   deepline billing limit --json
 `
   ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleLimit);
-  billing.command("set-limit").description("Set monthly spend guidance.").addHelpText(
+  billing.command("set-limit").description("Set monthly usage cap.").addHelpText(
     "after",
     `
 Notes:
   Mutates workspace billing settings. The argument is a Deepline credit amount,
-  not dollars and not provider credits. Guidance is advisory; it does not
-  replace the exact available-balance admission check.
+  not dollars and not provider credits. New calls are checked against the cap;
+  in-flight work can still finish and exceed it. Buying credits does not reset it.
 
 Examples:
   deepline billing set-limit 500
   deepline billing set-limit 500 --json
 `
   ).argument("<credits>", "Monthly credits limit").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleSetLimit);
-  billing.command("off").description("Disable monthly spend guidance.").addHelpText(
+  billing.command("off").description("Disable monthly usage cap.").addHelpText(
     "after",
     `
 Notes:
-  Mutates workspace billing settings by removing monthly Deepline spend guidance.
+  Mutates workspace billing settings by removing monthly Deepline usage cap.
 
 Examples:
   deepline billing off
@@ -16598,11 +16601,8 @@ function collectInlineSecretFindings(sourceCode) {
 var MAX_PLAY_BUNDLE_BYTES = 30 * 1024 * 1024;
 
 // ../plays/bundling/index.ts
-var PLAY_BUNDLE_CACHE_VERSION = 37;
-var PLAY_ARTIFACT_CACHE_DIR = join7(
-  tmpdir2(),
-  `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`
-);
+var PLAY_BUNDLE_CACHE_NAMESPACE = "deepline-play-artifacts-docflow-jsdoc";
+var PLAY_ARTIFACT_CACHE_DIR = join7(tmpdir2(), PLAY_BUNDLE_CACHE_NAMESPACE);
 var NODE_BUILTIN_SET = new Set(
   builtinModules.flatMap(
     (name) => name.startsWith("node:") ? [name, name.slice(5)] : [name, `node:${name}`]
@@ -35456,6 +35456,28 @@ function monitorBatchScope(options, kind) {
 function monitorBatchIdempotencyKey(kind, value) {
   return value?.trim() || `monitor-batch-${kind}-${randomUUID5()}`;
 }
+function legacyDryRunManifest(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+  const object = asRecord2(parsed);
+  if (object && asString(object.key) && asString(object.tool)) {
+    return raw;
+  }
+  const isBatchDocument = Array.isArray(parsed) || object !== null && (Object.prototype.hasOwnProperty.call(object, "monitors") || object.kind === "batch");
+  if (!isBatchDocument) return raw;
+  const lint = lintMonitorBatchInput(parsed);
+  if (!lint.normalized) {
+    throw new MonitorsUsageError(
+      lint.issues.filter((issue) => issue.severity === "error").map((issue) => `${issue.path || "batch"}: ${issue.message}`).join("; ")
+    );
+  }
+  return `${lint.normalized.monitors.map((monitor) => JSON.stringify(monitor)).join("\n")}
+`;
+}
 async function handleMonitorBatchDeploy(options) {
   if (!options.file?.trim()) {
     throw new MonitorsUsageError(
@@ -35478,6 +35500,9 @@ async function handleMonitorBatchDeploy(options) {
   if (!manifestNdjson.trim()) {
     throw new MonitorsUsageError("Monitor batch manifest is empty.");
   }
+  if (options.dryRun === true) {
+    manifestNdjson = legacyDryRunManifest(manifestNdjson);
+  }
   const idempotencyKey = monitorBatchIdempotencyKey(
     "deploy",
     options.idempotencyKey
@@ -35507,9 +35532,10 @@ async function handleMonitorBatch(kind, options) {
       `monitors batch ${kind} changes provider monitors asynchronously. Preview with --dry-run, then confirm with --yes.`
     );
   }
-  if (kind === "deactivate" && !options.reason?.trim()) {
+  const scope = monitorBatchScope(options, kind);
+  if (kind === "deactivate" && scope.kind === "target" && !options.reason?.trim()) {
     throw new MonitorsUsageError(
-      "monitors batch deactivate requires --reason (for example insufficient_balance or billing_failure)."
+      "monitors batch deactivate --target requires --reason (for example insufficient_balance or billing_failure). Omit --reason with --keys for a customer-requested teardown."
     );
   }
   const idempotencyKey = monitorBatchIdempotencyKey(
@@ -35518,7 +35544,7 @@ async function handleMonitorBatch(kind, options) {
   );
   const result = await new DeeplineClient().monitors.batch.submit({
     kind,
-    scope: monitorBatchScope(options, kind),
+    scope,
     dryRun: options.dryRun === true,
     ...options.reason?.trim() ? { deactivationReason: options.reason.trim() } : {},
     idempotencyKey
@@ -35723,7 +35749,10 @@ Examples:
       batch.command("deactivate").description(
         "Durably deactivate a selection through provider batch deletes."
       )
-    ).requiredOption("--reason <reason>", "Declared deactivation reason").option("--yes", "Confirm the asynchronous provider deactivation")
+    ).option(
+      "--reason <reason>",
+      "Declared policy reason; required with --target and omitted for a customer-requested --keys teardown"
+    ).option("--yes", "Confirm the asynchronous provider deactivation")
   ).action(
     monitorsAction(
       (options) => handleMonitorBatch("deactivate", options)

package/dist/index.d.mts

@@ -3260,7 +3260,10 @@ type MonitorBatchExistingSubmitOptions = {
     kind: 'audit' | 'deactivate' | 'reactivate' | 'repair';
     scope: MonitorBatchScope;
     dryRun?: boolean;
-    /** Required for deactivate; it is the declared reason shown by health/UI. */
+    /**
+     * A declared policy reason for target deactivation. Omit it for an explicit
+     * customer-owned key teardown; absent is the durable customer intent.
+     */
     deactivationReason?: string;
     /** Stable retry key. Reusing it joins the original durable operation. */
     idempotencyKey: string;

package/dist/index.d.ts

@@ -3260,7 +3260,10 @@ type MonitorBatchExistingSubmitOptions = {
     kind: 'audit' | 'deactivate' | 'reactivate' | 'repair';
     scope: MonitorBatchScope;
     dryRun?: boolean;
-    /** Required for deactivate; it is the declared reason shown by health/UI. */
+    /**
+     * A declared policy reason for target deactivation. Omit it for an explicit
+     * customer-owned key teardown; absent is the durable customer intent.
+     */
     deactivationReason?: string;
     /** Stable retry key. Reusing it joins the original durable operation. */
     idempotencyKey: string;

package/dist/index.js

@@ -860,7 +860,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.99",
+  version: "0.3.101",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/index.mjs

@@ -768,7 +768,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.99",
+  version: "0.3.101",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/plays/bundle-play-file.mjs

@@ -1964,7 +1964,7 @@ function inferBindingIo(statement) {
     ioConfidence: "inferred"
   };
 }
-var MERMAID_BLOCK = /\/\*\*\s*@mermaid(?:\s|\r?\n)([\s\S]*?)\*\//g;
+var JSDOC_BLOCK = /\/\*\*([\s\S]*?)\*\//g;
 var BLOCK_EXPORT_HEADER = /^[A-Za-z_$][\w$-]*$/;
 function cleanBlockBody(raw) {
   return raw.split(/\r?\n/).map((line) => /^\s*\*/.test(line) ? line.replace(/^\s*\* ?/, "") : line).join("\n").trim();
@@ -2151,9 +2151,12 @@ function materializeDocflow(block) {
 function parsePlayDocflowFile(sourceCode) {
   const errors = [];
   const rawBlocks = [];
-  MERMAID_BLOCK.lastIndex = 0;
-  for (const match of sourceCode.matchAll(MERMAID_BLOCK)) {
-    rawBlocks.push({ syntax: "mermaid", body: cleanBlockBody(match[1]) });
+  JSDOC_BLOCK.lastIndex = 0;
+  for (const match of sourceCode.matchAll(JSDOC_BLOCK)) {
+    const cleanedBody = cleanBlockBody(match[1]);
+    const mermaid = /^@mermaid(?:[ \t]+|\r?\n|$)([\s\S]*)$/.exec(cleanedBody);
+    if (!mermaid) continue;
+    rawBlocks.push({ syntax: "mermaid", body: mermaid[1].trim() });
   }
   if (rawBlocks.length === 0) return { blocks: [], bindings: [], errors };
   const rejectedNodeIds = /* @__PURE__ */ new Set();
@@ -2878,11 +2881,8 @@ function validatePlaySourceFilesHaveNoInlineSecrets(sourceFiles) {
 var MAX_PLAY_BUNDLE_BYTES = 30 * 1024 * 1024;
 
 // ../plays/bundling/index.ts
-var PLAY_BUNDLE_CACHE_VERSION = 37;
-var PLAY_ARTIFACT_CACHE_DIR = join(
-  tmpdir(),
-  `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`
-);
+var PLAY_BUNDLE_CACHE_NAMESPACE = "deepline-play-artifacts-docflow-jsdoc";
+var PLAY_ARTIFACT_CACHE_DIR = join(tmpdir(), PLAY_BUNDLE_CACHE_NAMESPACE);
 var PLAY_PROXY_NAMESPACE = "deepline-play-runtime-ref";
 var SOURCE_EXTENSIONS = [
   ".ts",
@@ -4867,7 +4867,6 @@ async function discoverPackagedLocalFiles(entryFile) {
 }
 
 // src/plays/bundle-play-file.ts
-var PLAY_BUNDLE_CACHE_VERSION2 = 37;
 var MODULE_DIR = dirname3(fileURLToPath(import.meta.url));
 var SDK_PACKAGE_ROOT = resolve3(MODULE_DIR, "..", "..");
 var SOURCE_REPO_ROOT = resolve3(SDK_PACKAGE_ROOT, "..", "..");
@@ -4917,10 +4916,7 @@ function createSdkPlayBundlingAdapter() {
   return {
     projectRoot: PROJECT_ROOT,
     nodeModulesDir: HAS_PACKAGED_BUNDLING_SOURCES ? resolve3(SDK_PACKAGE_ROOT, "node_modules") : resolve3(PROJECT_ROOT, "node_modules"),
-    cacheDir: join3(
-      tmpdir2(),
-      `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION2}`
-    ),
+    cacheDir: join3(tmpdir2(), PLAY_BUNDLE_CACHE_NAMESPACE),
     sdkSourceRoot: SDK_SOURCE_ROOT,
     sdkPackageJson: SDK_PACKAGE_JSON,
     sdkEntryFile: SDK_ENTRY_FILE,

package/dist/release.d.mts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.99";
+    readonly version: "0.3.101";
     readonly updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.d.ts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.99";
+    readonly version: "0.3.101";
     readonly updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.js

@@ -74,7 +74,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.99",
+  version: "0.3.101",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/release.mjs

@@ -48,7 +48,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.99",
+  version: "0.3.101",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.3.99",
+  "version": "0.3.101",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",