deepline 0.1.266 → 0.1.267

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

@@ -1,4 +1,4 @@
-import { SDK_API_CONTRACT, SDK_VERSION } from './version.js';
+import { SDK_API_CONTRACT, SDK_API_MAJOR, SDK_VERSION } from './version.js';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -87,6 +87,7 @@ function compatibilityCacheKey(
     baseUrl: baseUrl.replace(/\/$/, ''),
     version: SDK_VERSION,
     apiContract: SDK_API_CONTRACT,
+    apiMajor: SDK_API_MAJOR,
     command: command?.trim() || null,
     skillsVersion: skillsVersion ?? null,
   });
@@ -186,6 +187,7 @@ export async function checkSdkCompatibility(
       headers: {
         'User-Agent': `deepline-ts-sdk/${SDK_VERSION}`,
         'X-Deepline-SDK-Version': SDK_VERSION,
+        'X-Deepline-API-Major': String(SDK_API_MAJOR),
         'X-Deepline-API-Contract': SDK_API_CONTRACT,
       },
       signal: controller.signal,

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

@@ -12,9 +12,10 @@
  *
  * Edit THIS file by hand only for deliberate release decisions:
  *   - minor/major version bumps (set `version`),
- *   - `apiContract` cutovers (see `docs/sdk-runtime-compatibility.md`),
+ *   - API-major cutovers (set `contracts.api.currentMajor`; leave `version` to the
+ *     publish-time patch selector),
  *   - support-window moves (`minimumSupported` / `deprecatedBelow`).
- * The automation never touches `apiContract`, `minimumSupported`, or
+ * The automation never touches API compatibility policy, `minimumSupported`, or
  * `deprecatedBelow`.
  *
  * Everything else derives from these values:
@@ -35,6 +36,37 @@
 
 export type SdkReleaseChannel = 'latest' | 'next' | 'beta';
 
+/**
+ * The named public protocols. These are intentionally independent:
+ *
+ * - `api` is the HTTP SDK/CLI protocol. It is additive within a major.
+ * - `playArtifact` is the immutable client-bundled Play payload ABI.
+ * - `release` controls promotion/publishing; it is not a client protocol.
+ *
+ * Do not use an SDK package version or a date string as an artifact ABI.
+ */
+export type DeeplineContractPolicy = {
+  api: {
+    name: 'sdk-http-api';
+    currentMajor: number;
+    supportedMajors: readonly number[];
+    /** Transitional value for installed SDKs that only send the old header. */
+    legacyWireIds: readonly string[];
+  };
+  playArtifact: {
+    name: 'play-artifact-runtime';
+    currentVersion: number;
+    supportedVersions: readonly number[];
+  };
+  release: {
+    name: 'production-sdk-release';
+    /** npm may publish only from the active, healthy Production SHA. */
+    publishFrom: 'latest-successful-production-deployment';
+    /** A newer merge cancels an in-flight decision; reconciliation picks the last healthy SHA. */
+    coalesce: 'latest-healthy';
+  };
+};
+
 export type SdkSupportPolicy = {
   /**
    * Anything strictly below this returns `status: "unsupported"` from
@@ -57,6 +89,8 @@ export type SdkSupportPolicy = {
     minimumSupported: string;
     reason: string;
   }>;
+  /** Previously published wire contracts that remain supported. */
+  compatibleApiContracts?: readonly string[];
   /**
    * Published package versions that must keep working for direct SDK tool
    * callers. CI installs each package from npm and exercises `tools.get` and
@@ -77,12 +111,8 @@ export type SdkRelease = {
    * publish time (auto-bump); edit by hand only for minor/major releases.
    */
   version: string;
-  /**
-   * SDK/API contract identifier. Bump on incompatible protocol or schema
-   * changes between the installed SDK/CLI and the Deepline backend.
-   * See `docs/sdk-runtime-compatibility.md`.
-   */
-  apiContract: string;
+  /** Named compatibility policies. This is the only authored contract policy. */
+  contracts: DeeplineContractPolicy;
   /** Public support policy reported by `/api/v2/sdk/compat`. */
   supportPolicy: SdkSupportPolicy;
 };
@@ -125,8 +155,31 @@ export const SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: '0.1.266',
-  apiContract: '2026-07-admin-cli-local-cutover',
+  version: '0.1.267',
+  contracts: {
+    api: {
+      name: 'sdk-http-api',
+      // API v2 is append-only. A breaking public request/response change needs
+      // v3 and an explicit v2 support-window decision, never a patch release.
+      currentMajor: 2,
+      supportedMajors: [2],
+      // Accepted only to bridge SDKs released before X-Deepline-API-Major.
+      legacyWireIds: [
+        '2026-07-admin-cli-local-cutover',
+        '2026-07-native-monitor-launch-hard-cutover',
+      ],
+    },
+    playArtifact: {
+      name: 'play-artifact-runtime',
+      currentVersion: 2,
+      supportedVersions: [1, 2],
+    },
+    release: {
+      name: 'production-sdk-release',
+      publishFrom: 'latest-successful-production-deployment',
+      coalesce: 'latest-healthy',
+    },
+  },
   supportPolicy: {
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.219',

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

@@ -3,4 +3,8 @@
 import { SDK_RELEASE } from './release.js';
 
 export const SDK_VERSION: string = SDK_RELEASE.version;
-export const SDK_API_CONTRACT: string = SDK_RELEASE.apiContract;
+/** Numbered SDK HTTP API major sent by current SDK/CLI clients. */
+export const SDK_API_MAJOR: number = SDK_RELEASE.contracts.api.currentMajor;
+/** @deprecated Transitional wire id for pre-major-header SDKs only. */
+export const SDK_API_CONTRACT: string =
+  SDK_RELEASE.contracts.api.legacyWireIds[0] ?? `api-v${SDK_API_MAJOR}`;

package/dist/bundling-sources/shared_libs/play-runtime/context.ts

@@ -5432,13 +5432,13 @@ export class PlayContextImpl {
           this.rowStates.get(idx)?.results.set(fieldName, cellValue);
           const currentCellMeta =
             this.activeMapCellMeta?.get(rowKey)?.[fieldName];
-          const currentCellStatus =
+          const currentCellRecord =
             currentCellMeta &&
             typeof currentCellMeta === 'object' &&
-            !Array.isArray(currentCellMeta) &&
-            'status' in currentCellMeta
-              ? (currentCellMeta as { status?: unknown }).status
+            !Array.isArray(currentCellMeta)
+              ? (currentCellMeta as { status?: unknown; reused?: unknown })
               : null;
+          const currentCellStatus = currentCellRecord?.status ?? null;
           if (currentCellStatus === 'skipped') {
             if (
               shouldPersistMapCellField(fieldName) &&
@@ -5455,13 +5455,25 @@ export class PlayContextImpl {
             }
             continue;
           }
+          // A cell whose underlying durable work was fully satisfied from
+          // content-addressed receipts recorded a `cached`/`reused` cell-meta
+          // marker while the body ran (see resolveRequestsFromReceipt). Emitting
+          // an unconditional `completed` here would clobber that marker to a
+          // non-reused `completed`, so the run's per-column `cached` counter
+          // reads 0 on a full-reuse rerun even though provider spend was 0.
+          // Preserve the reuse signal so `columnStats.cached` reflects real
+          // receipt reuse consistent with the near-zero provider spend.
+          const cellWasReused =
+            currentCellStatus === 'cached' &&
+            currentCellRecord?.reused === true;
           this.emitScopedFieldMetaUpdate({
             rowId: idx,
             key: rowKey,
             tableNamespace: normalizedTableNamespace,
             fieldName,
-            status: 'completed',
-            stage: 'completed',
+            status: cellWasReused ? 'cached' : 'completed',
+            stage: cellWasReused ? 'cached' : 'completed',
+            ...(cellWasReused ? { reused: true } : {}),
             completedAt: Date.now(),
             dataPatch: shouldPersistMapCellField(fieldName)
               ? { [fieldName]: cellValue }

package/dist/bundling-sources/shared_libs/play-runtime/dataset-lifecycle-log.ts

@@ -0,0 +1,30 @@
+type DatasetLogIdentity = {
+  path: string;
+  tableNamespace: string;
+};
+
+/**
+ * Dataset paths identify runtime state. They are not CLI export selectors: a
+ * returned result field (for example `result.rows`) is the supported export
+ * handle. Keep this distinction explicit in operator logs.
+ */
+export function formatDatasetRegistrationLog(input: {
+  dataset: DatasetLogIdentity;
+  rows: number;
+}): string {
+  if (input.rows === 0) {
+    return `Dataset ${input.dataset.path} registered (0 rows); export unavailable: empty dataset`;
+  }
+  return `Dataset ${input.dataset.path} registered (${input.rows} rows); awaiting terminal persistence`;
+}
+
+export function formatDatasetAvailabilityLog(input: {
+  runId: string;
+  dataset: DatasetLogIdentity;
+  persistedRows: number;
+}): string {
+  if (input.persistedRows === 0) {
+    return `Dataset ${input.dataset.path} available: 0 persisted rows; export unavailable: empty dataset`;
+  }
+  return `Dataset ${input.dataset.path} available: ${input.persistedRows} persisted rows; inspect deepline runs get ${input.runId} --full --json for the verified export action`;
+}

package/dist/cli/index.js

@@ -718,8 +718,31 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.266",
-  apiContract: "2026-07-admin-cli-local-cutover",
+  version: "0.1.267",
+  contracts: {
+    api: {
+      name: "sdk-http-api",
+      // API v2 is append-only. A breaking public request/response change needs
+      // v3 and an explicit v2 support-window decision, never a patch release.
+      currentMajor: 2,
+      supportedMajors: [2],
+      // Accepted only to bridge SDKs released before X-Deepline-API-Major.
+      legacyWireIds: [
+        "2026-07-admin-cli-local-cutover",
+        "2026-07-native-monitor-launch-hard-cutover"
+      ]
+    },
+    playArtifact: {
+      name: "play-artifact-runtime",
+      currentVersion: 2,
+      supportedVersions: [1, 2]
+    },
+    release: {
+      name: "production-sdk-release",
+      publishFrom: "latest-successful-production-deployment",
+      coalesce: "latest-healthy"
+    }
+  },
   supportPolicy: {
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.219",
@@ -816,7 +839,8 @@ var SDK_RELEASE = {
 
 // src/version.ts
 var SDK_VERSION = SDK_RELEASE.version;
-var SDK_API_CONTRACT = SDK_RELEASE.apiContract;
+var SDK_API_MAJOR = SDK_RELEASE.contracts.api.currentMajor;
+var SDK_API_CONTRACT = SDK_RELEASE.contracts.api.legacyWireIds[0] ?? `api-v${SDK_API_MAJOR}`;
 
 // src/agent-runtime.ts
 var import_node_os2 = require("os");
@@ -4838,6 +4862,7 @@ function compatibilityCacheKey(baseUrl, command, skillsVersion) {
     baseUrl: baseUrl.replace(/\/$/, ""),
     version: SDK_VERSION,
     apiContract: SDK_API_CONTRACT,
+    apiMajor: SDK_API_MAJOR,
     command: command?.trim() || null,
     skillsVersion: skillsVersion ?? null
   });
@@ -4906,6 +4931,7 @@ async function checkSdkCompatibility(baseUrl, options = {}) {
       headers: {
         "User-Agent": `deepline-ts-sdk/${SDK_VERSION}`,
         "X-Deepline-SDK-Version": SDK_VERSION,
+        "X-Deepline-API-Major": String(SDK_API_MAJOR),
         "X-Deepline-API-Contract": SDK_API_CONTRACT
       },
       signal: controller.signal
@@ -5284,26 +5310,29 @@ function browserOpeningDisabled() {
   ).trim().toLowerCase();
   return value === "1" || value === "true" || value === "yes" || value === "on";
 }
-function openInBrowser(url) {
+function openInBrowser(url, options = {}) {
   try {
-    if (browserOpeningDisabled()) return;
+    if (browserOpeningDisabled()) return "failed";
     const targetUrl = String(url || "").trim();
-    if (!targetUrl) return;
-    if (!claimBrowserOpen(Date.now(), void 0, targetUrl)) return;
+    if (!targetUrl) return "failed";
+    if (options.deduplicate !== false && !claimBrowserOpen(Date.now(), void 0, targetUrl)) {
+      return "suppressed";
+    }
     const allowFocus = true;
     if (process.platform === "darwin") {
-      openUrlMacos(targetUrl, allowFocus);
-      return;
+      return openUrlMacos(targetUrl, allowFocus) ? "opened" : "failed";
     }
-    if (!allowFocus) return;
+    if (!allowFocus) return "failed";
     if (process.platform === "win32") {
       childProcess.execFileSync("cmd.exe", ["/c", "start", "", targetUrl], {
         stdio: "ignore"
       });
-      return;
+      return "opened";
     }
     childProcess.execFileSync("xdg-open", [targetUrl], { stdio: "ignore" });
+    return "opened";
   } catch {
+    return "failed";
   }
 }
 function sleep3(ms) {
@@ -29514,6 +29543,18 @@ function inferNpmGlobalPrefixFromEntrypoint(entrypoint) {
   const prefix = normalized.startsWith("/") && prefixParts[0] !== "" ? `/${prefixParts.join("/")}` : prefixParts.join("/");
   return prefix || null;
 }
+function isHomebrewFormulaEntrypoint(entrypoint) {
+  const normalized = (() => {
+    try {
+      return (0, import_node_fs17.realpathSync)(entrypoint);
+    } catch {
+      return (0, import_node_path19.resolve)(entrypoint);
+    }
+  })();
+  const parts = normalized.split(/[\\/]+/);
+  const cellarIndex = parts.lastIndexOf("Cellar");
+  return cellarIndex >= 0 && parts[cellarIndex + 1] === "deepline" && parts.slice(cellarIndex + 3).includes("libexec");
+}
 function resolveUpdatePlan(options = {}) {
   const env = options.env ?? process.env;
   const homeDir2 = options.homeDir ?? (0, import_node_os14.homedir)();
@@ -29526,6 +29567,12 @@ function resolveUpdatePlan(options = {}) {
       manualCommand: buildSourceUpdateCommand(sourceRoot)
     };
   }
+  if (entrypoint && isHomebrewFormulaEntrypoint(entrypoint)) {
+    return {
+      kind: "homebrew",
+      manualCommand: "brew upgrade deepline"
+    };
+  }
   const sidecarPlan = resolvePythonSidecarUpdatePlan({
     entrypoint,
     env,
@@ -29557,7 +29604,7 @@ function resolveUpdatePlan(options = {}) {
 }
 var AUTO_UPDATE_FAILURE_FILE = ".auto-update-failure.json";
 function autoUpdateFailurePath(plan) {
-  if (plan.kind === "source") return null;
+  if (plan.kind === "source" || plan.kind === "homebrew") return null;
   if (plan.kind === "python-sidecar") {
     return (0, import_node_path19.join)(plan.stateDir, AUTO_UPDATE_FAILURE_FILE);
   }
@@ -29570,7 +29617,7 @@ function autoUpdateFailurePath(plan) {
   );
 }
 function autoUpdatePackageSpec(plan) {
-  if (plan.kind === "source") return "";
+  if (plan.kind === "source" || plan.kind === "homebrew") return "";
   if (plan.kind === "python-sidecar") return plan.packageSpec;
   return plan.args[plan.args.length - 1] ?? plan.manualCommand;
 }
@@ -29591,7 +29638,7 @@ function readAutoUpdateFailure(plan) {
 }
 function writeAutoUpdateFailure(plan, exitCode) {
   const path = autoUpdateFailurePath(plan);
-  if (!path || plan.kind === "source") return;
+  if (!path || plan.kind === "source" || plan.kind === "homebrew") return;
   const marker = {
     kind: plan.kind,
     packageSpec: autoUpdatePackageSpec(plan),
@@ -29616,7 +29663,9 @@ function clearAutoUpdateFailure(plan) {
 }
 function matchingAutoUpdateFailure(plan) {
   const marker = readAutoUpdateFailure(plan);
-  if (!marker || plan.kind === "source") return null;
+  if (!marker || plan.kind === "source" || plan.kind === "homebrew") {
+    return null;
+  }
   if (marker.kind !== plan.kind) return null;
   if (marker.packageSpec !== autoUpdatePackageSpec(plan)) return null;
   return marker;
@@ -29874,6 +29923,8 @@ async function runUpdatePlan(plan) {
     });
   } else if (plan.kind === "python-sidecar") {
     exitCode = await runPythonSidecarUpdatePlan(plan);
+  } else if (plan.kind === "homebrew") {
+    exitCode = 0;
   }
   if (exitCode === 0) {
     clearAutoUpdateFailure(plan);
@@ -29912,6 +29963,9 @@ async function runUpdateCommand(options, dependencies = {}) {
         lines: plan.kind === "source" ? [
           "This Deepline CLI is running from SDK source, so it cannot safely update itself like an npm global.",
           `Update the backing checkout with: ${plan.manualCommand}`
+        ] : plan.kind === "homebrew" ? [
+          "This Deepline CLI was installed by Homebrew, which owns its upgrades.",
+          `Update it with: ${plan.manualCommand}`
         ] : plan.kind === "python-sidecar" ? [
           "This Deepline CLI is running from the Python-managed SDK sidecar.",
           "Updating will refresh that sidecar, not a global npm binary."
@@ -29936,7 +29990,7 @@ async function runUpdateCommand(options, dependencies = {}) {
     );
     return 0;
   }
-  if (plan.kind === "source") {
+  if (plan.kind === "source" || plan.kind === "homebrew") {
     printCommandEnvelope({ ...plan, render }, { json: false });
     return 0;
   }
@@ -29955,6 +30009,8 @@ function registerUpdateCommand(program) {
     `
 Notes:
   For the published npm CLI, this runs npm install -g deepline@latest.
+  For a Homebrew installation, this prints brew upgrade deepline; Homebrew
+  owns formula upgrades and Deepline never runs npm inside its Cellar.
   For Python-managed SDK sidecars, this refreshes the sidecar that launched
   the current SDK CLI instead of changing a global npm binary.
   For repo-backed SDK wrappers such as cli-env sdk-prod or sdk-worktree, this
@@ -30074,14 +30130,37 @@ function resolveScopeRoot(scope) {
 function authScopeForSetup(scope) {
   return scope === "local" ? "folder" : "global";
 }
-function shouldOpenSetupAuthorization(runtime = detectAgentRuntime()) {
-  return runtime !== "claude_cowork";
-}
 function openSetupAuthorization(authorizationUrl, options = {}) {
   const url = authorizationUrl.trim();
-  if (!url || !shouldOpenSetupAuthorization(options.runtime)) return false;
-  (options.open ?? openInBrowser)(url);
-  return true;
+  if (!url) return "failed";
+  if (options.open) return options.open(url);
+  const result = openInBrowser(url, { deduplicate: false });
+  return result === "opened" ? "opened" : "failed";
+}
+function buildPendingAuthorizationOutput(input2) {
+  const authorizationUrl = input2.authorizationUrl.trim();
+  if (input2.browserOpenStatus === "opened") {
+    return {
+      authorizationUrl: null,
+      next: `Complete browser approval, then run: ${input2.resumeCommand}`,
+      lines: ["Complete authorization in the browser window Deepline opened."]
+    };
+  }
+  if (authorizationUrl) {
+    return {
+      authorizationUrl,
+      next: `Open the authorization URL, approve it, then run: ${input2.resumeCommand}`,
+      lines: [
+        "Browser launch failed. Open the authorization URL to continue.",
+        authorizationUrl
+      ]
+    };
+  }
+  return {
+    authorizationUrl: null,
+    next: `Authorization is pending without a browser URL. Retry: ${input2.resumeCommand}`,
+    lines: ["Authorization is pending, but no browser URL was returned."]
+  };
 }
 function setupStatePath(baseUrl, scope, root) {
   return scope === "local" && root ? (0, import_node_path20.join)(root, ".deepline", "setup", "state.json") : (0, import_node_path20.join)(sdkCliStateDirPath(baseUrl), "setup.json");
@@ -30111,15 +30190,6 @@ function parseCapturedJson(stdout) {
 function asRecord2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
-function printCapturedAuthorizationUrl(stdout) {
-  const urls = stdout.match(/https:\/\/[^\s]+/g) ?? [];
-  for (const url of new Set(
-    urls.map((value) => value.replace(/[).,]+$/, ""))
-  )) {
-    process.stderr.write(`Authorize Deepline: ${url}
-`);
-  }
-}
 function safeRead(path) {
   try {
     return (0, import_node_fs18.readFileSync)(path, "utf8");
@@ -30458,18 +30528,32 @@ function pendingResult(input2) {
     status: "authorization_pending",
     phases: input2.phases
   });
+  let browserOpenStatus = "failed";
   if (input2.authorizationUrl) {
-    openSetupAuthorization(input2.authorizationUrl);
-    process.stderr.write(`Authorize Deepline: ${input2.authorizationUrl}
+    browserOpenStatus = openSetupAuthorization(input2.authorizationUrl);
+    if (browserOpenStatus === "opened") {
+      process.stderr.write(
+        "Opened Deepline authorization in your browser. Complete approval there.\n"
+      );
+    } else if (browserOpenStatus === "failed") {
+      process.stderr.write(`Authorize Deepline: ${input2.authorizationUrl}
 `);
+    }
   }
+  const pendingOutput = buildPendingAuthorizationOutput({
+    authorizationUrl: input2.authorizationUrl,
+    browserOpenStatus,
+    resumeCommand: setupResumeCommand(input2.baseUrl, input2.scope)
+  });
   printCommandEnvelope(
     {
       ok: true,
       status: "authorization_pending",
       complete: false,
       scope: input2.scope,
-      authorizationUrl: input2.authorizationUrl || null,
+      authorizationUrl: pendingOutput.authorizationUrl,
+      browserOpened: browserOpenStatus === "opened",
+      browserOpenStatus,
       statePath,
       phases: input2.phases,
       currentPhase: "auth",
@@ -30479,15 +30563,12 @@ function pendingResult(input2) {
         scope: input2.scope,
         phase: "auth"
       }),
-      next: `Approve the link, then run: ${setupResumeCommand(input2.baseUrl, input2.scope)}`,
+      next: pendingOutput.next,
       render: {
         sections: [
           {
             title: "setup",
-            lines: [
-              "Authorization is waiting for browser approval.",
-              ...input2.authorizationUrl ? [input2.authorizationUrl] : []
-            ]
+            lines: pendingOutput.lines
           }
         ]
       }
@@ -30656,10 +30737,9 @@ async function runSetupCommand(options) {
     const pending = readPendingAuthClaim(baseUrl, authScope);
     if (pending) {
       process.stderr.write("Checking pending Deepline authorization...\n");
-      const waited = await captureStdout2(
+      await captureStdout2(
         () => handleWait(["--timeout", "1", "--auth-scope", authScope])
       );
-      printCapturedAuthorizationUrl(waited.stdout);
       auth = await readAuthStatus(authScope);
       const resumedAuthFailure = reportSetupAuthStatusFailure({
         auth,
@@ -30695,7 +30775,6 @@ async function runSetupCommand(options) {
     const registered = await captureStdout2(
       () => handleRegister(["--wait", waitMode, "--auth-scope", authScope])
     );
-    printCapturedAuthorizationUrl(registered.stdout);
     if (registered.exitCode !== 0) {
       return reportSetupPhaseFailure({
         baseUrl,

package/dist/cli/index.mjs

@@ -703,8 +703,31 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.266",
-  apiContract: "2026-07-admin-cli-local-cutover",
+  version: "0.1.267",
+  contracts: {
+    api: {
+      name: "sdk-http-api",
+      // API v2 is append-only. A breaking public request/response change needs
+      // v3 and an explicit v2 support-window decision, never a patch release.
+      currentMajor: 2,
+      supportedMajors: [2],
+      // Accepted only to bridge SDKs released before X-Deepline-API-Major.
+      legacyWireIds: [
+        "2026-07-admin-cli-local-cutover",
+        "2026-07-native-monitor-launch-hard-cutover"
+      ]
+    },
+    playArtifact: {
+      name: "play-artifact-runtime",
+      currentVersion: 2,
+      supportedVersions: [1, 2]
+    },
+    release: {
+      name: "production-sdk-release",
+      publishFrom: "latest-successful-production-deployment",
+      coalesce: "latest-healthy"
+    }
+  },
   supportPolicy: {
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.219",
@@ -801,7 +824,8 @@ var SDK_RELEASE = {
 
 // src/version.ts
 var SDK_VERSION = SDK_RELEASE.version;
-var SDK_API_CONTRACT = SDK_RELEASE.apiContract;
+var SDK_API_MAJOR = SDK_RELEASE.contracts.api.currentMajor;
+var SDK_API_CONTRACT = SDK_RELEASE.contracts.api.legacyWireIds[0] ?? `api-v${SDK_API_MAJOR}`;
 
 // src/agent-runtime.ts
 import { homedir as homedir2 } from "os";
@@ -4823,6 +4847,7 @@ function compatibilityCacheKey(baseUrl, command, skillsVersion) {
     baseUrl: baseUrl.replace(/\/$/, ""),
     version: SDK_VERSION,
     apiContract: SDK_API_CONTRACT,
+    apiMajor: SDK_API_MAJOR,
     command: command?.trim() || null,
     skillsVersion: skillsVersion ?? null
   });
@@ -4891,6 +4916,7 @@ async function checkSdkCompatibility(baseUrl, options = {}) {
       headers: {
         "User-Agent": `deepline-ts-sdk/${SDK_VERSION}`,
         "X-Deepline-SDK-Version": SDK_VERSION,
+        "X-Deepline-API-Major": String(SDK_API_MAJOR),
         "X-Deepline-API-Contract": SDK_API_CONTRACT
       },
       signal: controller.signal
@@ -5281,26 +5307,29 @@ function browserOpeningDisabled() {
   ).trim().toLowerCase();
   return value === "1" || value === "true" || value === "yes" || value === "on";
 }
-function openInBrowser(url) {
+function openInBrowser(url, options = {}) {
   try {
-    if (browserOpeningDisabled()) return;
+    if (browserOpeningDisabled()) return "failed";
     const targetUrl = String(url || "").trim();
-    if (!targetUrl) return;
-    if (!claimBrowserOpen(Date.now(), void 0, targetUrl)) return;
+    if (!targetUrl) return "failed";
+    if (options.deduplicate !== false && !claimBrowserOpen(Date.now(), void 0, targetUrl)) {
+      return "suppressed";
+    }
     const allowFocus = true;
     if (process.platform === "darwin") {
-      openUrlMacos(targetUrl, allowFocus);
-      return;
+      return openUrlMacos(targetUrl, allowFocus) ? "opened" : "failed";
     }
-    if (!allowFocus) return;
+    if (!allowFocus) return "failed";
     if (process.platform === "win32") {
       childProcess.execFileSync("cmd.exe", ["/c", "start", "", targetUrl], {
         stdio: "ignore"
       });
-      return;
+      return "opened";
     }
     childProcess.execFileSync("xdg-open", [targetUrl], { stdio: "ignore" });
+    return "opened";
   } catch {
+    return "failed";
   }
 }
 function sleep3(ms) {
@@ -29571,6 +29600,18 @@ function inferNpmGlobalPrefixFromEntrypoint(entrypoint) {
   const prefix = normalized.startsWith("/") && prefixParts[0] !== "" ? `/${prefixParts.join("/")}` : prefixParts.join("/");
   return prefix || null;
 }
+function isHomebrewFormulaEntrypoint(entrypoint) {
+  const normalized = (() => {
+    try {
+      return realpathSync3(entrypoint);
+    } catch {
+      return resolve13(entrypoint);
+    }
+  })();
+  const parts = normalized.split(/[\\/]+/);
+  const cellarIndex = parts.lastIndexOf("Cellar");
+  return cellarIndex >= 0 && parts[cellarIndex + 1] === "deepline" && parts.slice(cellarIndex + 3).includes("libexec");
+}
 function resolveUpdatePlan(options = {}) {
   const env = options.env ?? process.env;
   const homeDir2 = options.homeDir ?? homedir12();
@@ -29583,6 +29624,12 @@ function resolveUpdatePlan(options = {}) {
       manualCommand: buildSourceUpdateCommand(sourceRoot)
     };
   }
+  if (entrypoint && isHomebrewFormulaEntrypoint(entrypoint)) {
+    return {
+      kind: "homebrew",
+      manualCommand: "brew upgrade deepline"
+    };
+  }
   const sidecarPlan = resolvePythonSidecarUpdatePlan({
     entrypoint,
     env,
@@ -29614,7 +29661,7 @@ function resolveUpdatePlan(options = {}) {
 }
 var AUTO_UPDATE_FAILURE_FILE = ".auto-update-failure.json";
 function autoUpdateFailurePath(plan) {
-  if (plan.kind === "source") return null;
+  if (plan.kind === "source" || plan.kind === "homebrew") return null;
   if (plan.kind === "python-sidecar") {
     return join15(plan.stateDir, AUTO_UPDATE_FAILURE_FILE);
   }
@@ -29627,7 +29674,7 @@ function autoUpdateFailurePath(plan) {
   );
 }
 function autoUpdatePackageSpec(plan) {
-  if (plan.kind === "source") return "";
+  if (plan.kind === "source" || plan.kind === "homebrew") return "";
   if (plan.kind === "python-sidecar") return plan.packageSpec;
   return plan.args[plan.args.length - 1] ?? plan.manualCommand;
 }
@@ -29648,7 +29695,7 @@ function readAutoUpdateFailure(plan) {
 }
 function writeAutoUpdateFailure(plan, exitCode) {
   const path = autoUpdateFailurePath(plan);
-  if (!path || plan.kind === "source") return;
+  if (!path || plan.kind === "source" || plan.kind === "homebrew") return;
   const marker = {
     kind: plan.kind,
     packageSpec: autoUpdatePackageSpec(plan),
@@ -29673,7 +29720,9 @@ function clearAutoUpdateFailure(plan) {
 }
 function matchingAutoUpdateFailure(plan) {
   const marker = readAutoUpdateFailure(plan);
-  if (!marker || plan.kind === "source") return null;
+  if (!marker || plan.kind === "source" || plan.kind === "homebrew") {
+    return null;
+  }
   if (marker.kind !== plan.kind) return null;
   if (marker.packageSpec !== autoUpdatePackageSpec(plan)) return null;
   return marker;
@@ -29931,6 +29980,8 @@ async function runUpdatePlan(plan) {
     });
   } else if (plan.kind === "python-sidecar") {
     exitCode = await runPythonSidecarUpdatePlan(plan);
+  } else if (plan.kind === "homebrew") {
+    exitCode = 0;
   }
   if (exitCode === 0) {
     clearAutoUpdateFailure(plan);
@@ -29969,6 +30020,9 @@ async function runUpdateCommand(options, dependencies = {}) {
         lines: plan.kind === "source" ? [
           "This Deepline CLI is running from SDK source, so it cannot safely update itself like an npm global.",
           `Update the backing checkout with: ${plan.manualCommand}`
+        ] : plan.kind === "homebrew" ? [
+          "This Deepline CLI was installed by Homebrew, which owns its upgrades.",
+          `Update it with: ${plan.manualCommand}`
         ] : plan.kind === "python-sidecar" ? [
           "This Deepline CLI is running from the Python-managed SDK sidecar.",
           "Updating will refresh that sidecar, not a global npm binary."
@@ -29993,7 +30047,7 @@ async function runUpdateCommand(options, dependencies = {}) {
     );
     return 0;
   }
-  if (plan.kind === "source") {
+  if (plan.kind === "source" || plan.kind === "homebrew") {
     printCommandEnvelope({ ...plan, render }, { json: false });
     return 0;
   }
@@ -30012,6 +30066,8 @@ function registerUpdateCommand(program) {
     `
 Notes:
   For the published npm CLI, this runs npm install -g deepline@latest.
+  For a Homebrew installation, this prints brew upgrade deepline; Homebrew
+  owns formula upgrades and Deepline never runs npm inside its Cellar.
   For Python-managed SDK sidecars, this refreshes the sidecar that launched
   the current SDK CLI instead of changing a global npm binary.
   For repo-backed SDK wrappers such as cli-env sdk-prod or sdk-worktree, this
@@ -30139,14 +30195,37 @@ function resolveScopeRoot(scope) {
 function authScopeForSetup(scope) {
   return scope === "local" ? "folder" : "global";
 }
-function shouldOpenSetupAuthorization(runtime = detectAgentRuntime()) {
-  return runtime !== "claude_cowork";
-}
 function openSetupAuthorization(authorizationUrl, options = {}) {
   const url = authorizationUrl.trim();
-  if (!url || !shouldOpenSetupAuthorization(options.runtime)) return false;
-  (options.open ?? openInBrowser)(url);
-  return true;
+  if (!url) return "failed";
+  if (options.open) return options.open(url);
+  const result = openInBrowser(url, { deduplicate: false });
+  return result === "opened" ? "opened" : "failed";
+}
+function buildPendingAuthorizationOutput(input2) {
+  const authorizationUrl = input2.authorizationUrl.trim();
+  if (input2.browserOpenStatus === "opened") {
+    return {
+      authorizationUrl: null,
+      next: `Complete browser approval, then run: ${input2.resumeCommand}`,
+      lines: ["Complete authorization in the browser window Deepline opened."]
+    };
+  }
+  if (authorizationUrl) {
+    return {
+      authorizationUrl,
+      next: `Open the authorization URL, approve it, then run: ${input2.resumeCommand}`,
+      lines: [
+        "Browser launch failed. Open the authorization URL to continue.",
+        authorizationUrl
+      ]
+    };
+  }
+  return {
+    authorizationUrl: null,
+    next: `Authorization is pending without a browser URL. Retry: ${input2.resumeCommand}`,
+    lines: ["Authorization is pending, but no browser URL was returned."]
+  };
 }
 function setupStatePath(baseUrl, scope, root) {
   return scope === "local" && root ? join16(root, ".deepline", "setup", "state.json") : join16(sdkCliStateDirPath(baseUrl), "setup.json");
@@ -30176,15 +30255,6 @@ function parseCapturedJson(stdout) {
 function asRecord2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
-function printCapturedAuthorizationUrl(stdout) {
-  const urls = stdout.match(/https:\/\/[^\s]+/g) ?? [];
-  for (const url of new Set(
-    urls.map((value) => value.replace(/[).,]+$/, ""))
-  )) {
-    process.stderr.write(`Authorize Deepline: ${url}
-`);
-  }
-}
 function safeRead(path) {
   try {
     return readFileSync14(path, "utf8");
@@ -30523,18 +30593,32 @@ function pendingResult(input2) {
     status: "authorization_pending",
     phases: input2.phases
   });
+  let browserOpenStatus = "failed";
   if (input2.authorizationUrl) {
-    openSetupAuthorization(input2.authorizationUrl);
-    process.stderr.write(`Authorize Deepline: ${input2.authorizationUrl}
+    browserOpenStatus = openSetupAuthorization(input2.authorizationUrl);
+    if (browserOpenStatus === "opened") {
+      process.stderr.write(
+        "Opened Deepline authorization in your browser. Complete approval there.\n"
+      );
+    } else if (browserOpenStatus === "failed") {
+      process.stderr.write(`Authorize Deepline: ${input2.authorizationUrl}
 `);
+    }
   }
+  const pendingOutput = buildPendingAuthorizationOutput({
+    authorizationUrl: input2.authorizationUrl,
+    browserOpenStatus,
+    resumeCommand: setupResumeCommand(input2.baseUrl, input2.scope)
+  });
   printCommandEnvelope(
     {
       ok: true,
       status: "authorization_pending",
       complete: false,
       scope: input2.scope,
-      authorizationUrl: input2.authorizationUrl || null,
+      authorizationUrl: pendingOutput.authorizationUrl,
+      browserOpened: browserOpenStatus === "opened",
+      browserOpenStatus,
       statePath,
       phases: input2.phases,
       currentPhase: "auth",
@@ -30544,15 +30628,12 @@ function pendingResult(input2) {
         scope: input2.scope,
         phase: "auth"
       }),
-      next: `Approve the link, then run: ${setupResumeCommand(input2.baseUrl, input2.scope)}`,
+      next: pendingOutput.next,
       render: {
         sections: [
           {
             title: "setup",
-            lines: [
-              "Authorization is waiting for browser approval.",
-              ...input2.authorizationUrl ? [input2.authorizationUrl] : []
-            ]
+            lines: pendingOutput.lines
           }
         ]
       }
@@ -30721,10 +30802,9 @@ async function runSetupCommand(options) {
     const pending = readPendingAuthClaim(baseUrl, authScope);
     if (pending) {
       process.stderr.write("Checking pending Deepline authorization...\n");
-      const waited = await captureStdout2(
+      await captureStdout2(
         () => handleWait(["--timeout", "1", "--auth-scope", authScope])
       );
-      printCapturedAuthorizationUrl(waited.stdout);
       auth = await readAuthStatus(authScope);
       const resumedAuthFailure = reportSetupAuthStatusFailure({
         auth,
@@ -30760,7 +30840,6 @@ async function runSetupCommand(options) {
     const registered = await captureStdout2(
       () => handleRegister(["--wait", waitMode, "--auth-scope", authScope])
     );
-    printCapturedAuthorizationUrl(registered.stdout);
     if (registered.exitCode !== 0) {
       return reportSetupPhaseFailure({
         baseUrl,

package/dist/index.d.mts

@@ -2703,6 +2703,7 @@ declare class RunObserveTransportUnavailableError extends Error {
 }
 
 declare const SDK_VERSION: string;
+/** @deprecated Transitional wire id for pre-major-header SDKs only. */
 declare const SDK_API_CONTRACT: string;
 
 /**

package/dist/index.d.ts

@@ -2703,6 +2703,7 @@ declare class RunObserveTransportUnavailableError extends Error {
 }
 
 declare const SDK_VERSION: string;
+/** @deprecated Transitional wire id for pre-major-header SDKs only. */
 declare const SDK_API_CONTRACT: string;
 
 /**

package/dist/index.js

@@ -437,8 +437,31 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.266",
-  apiContract: "2026-07-admin-cli-local-cutover",
+  version: "0.1.267",
+  contracts: {
+    api: {
+      name: "sdk-http-api",
+      // API v2 is append-only. A breaking public request/response change needs
+      // v3 and an explicit v2 support-window decision, never a patch release.
+      currentMajor: 2,
+      supportedMajors: [2],
+      // Accepted only to bridge SDKs released before X-Deepline-API-Major.
+      legacyWireIds: [
+        "2026-07-admin-cli-local-cutover",
+        "2026-07-native-monitor-launch-hard-cutover"
+      ]
+    },
+    playArtifact: {
+      name: "play-artifact-runtime",
+      currentVersion: 2,
+      supportedVersions: [1, 2]
+    },
+    release: {
+      name: "production-sdk-release",
+      publishFrom: "latest-successful-production-deployment",
+      coalesce: "latest-healthy"
+    }
+  },
   supportPolicy: {
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.219",
@@ -535,7 +558,8 @@ var SDK_RELEASE = {
 
 // src/version.ts
 var SDK_VERSION = SDK_RELEASE.version;
-var SDK_API_CONTRACT = SDK_RELEASE.apiContract;
+var SDK_API_MAJOR = SDK_RELEASE.contracts.api.currentMajor;
+var SDK_API_CONTRACT = SDK_RELEASE.contracts.api.legacyWireIds[0] ?? `api-v${SDK_API_MAJOR}`;
 
 // src/agent-runtime.ts
 var import_node_os2 = require("os");

package/dist/index.mjs

@@ -367,8 +367,31 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.266",
-  apiContract: "2026-07-admin-cli-local-cutover",
+  version: "0.1.267",
+  contracts: {
+    api: {
+      name: "sdk-http-api",
+      // API v2 is append-only. A breaking public request/response change needs
+      // v3 and an explicit v2 support-window decision, never a patch release.
+      currentMajor: 2,
+      supportedMajors: [2],
+      // Accepted only to bridge SDKs released before X-Deepline-API-Major.
+      legacyWireIds: [
+        "2026-07-admin-cli-local-cutover",
+        "2026-07-native-monitor-launch-hard-cutover"
+      ]
+    },
+    playArtifact: {
+      name: "play-artifact-runtime",
+      currentVersion: 2,
+      supportedVersions: [1, 2]
+    },
+    release: {
+      name: "production-sdk-release",
+      publishFrom: "latest-successful-production-deployment",
+      coalesce: "latest-healthy"
+    }
+  },
   supportPolicy: {
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.219",
@@ -465,7 +488,8 @@ var SDK_RELEASE = {
 
 // src/version.ts
 var SDK_VERSION = SDK_RELEASE.version;
-var SDK_API_CONTRACT = SDK_RELEASE.apiContract;
+var SDK_API_MAJOR = SDK_RELEASE.contracts.api.currentMajor;
+var SDK_API_CONTRACT = SDK_RELEASE.contracts.api.legacyWireIds[0] ?? `api-v${SDK_API_MAJOR}`;
 
 // src/agent-runtime.ts
 import { homedir as homedir2 } from "os";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.266",
+  "version": "0.1.267",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {
@@ -62,6 +62,7 @@
     "typescript": "^6.0.2"
   },
   "deepline": {
-    "apiContract": "2026-07-admin-cli-local-cutover"
+    "apiContract": "2026-07-admin-cli-local-cutover",
+    "apiMajor": 2
   }
 }