deepline 0.1.32 → 0.1.35

package/dist/cli/index.mjs

@@ -4,7 +4,7 @@
 import { Command as Command2 } from "commander";
 
 // src/config.ts
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { dirname, join, resolve } from "path";
 
@@ -44,19 +44,12 @@ var ConfigError = class extends DeeplineError {
 };
 
 // src/config.ts
+var HOST_URL_ENV = "DEEPLINE_HOST_URL";
+var API_KEY_ENV = "DEEPLINE_API_KEY";
 var PROD_URL = "https://code.deepline.com";
 var DEFAULT_TIMEOUT = 6e4;
 var DEFAULT_MAX_RETRIES = 3;
-var ACTIVE_DEEPLINE_ENV_FILE = ".env.deepline";
-function isProdBaseUrl(baseUrl) {
-  return baseUrl.trim().replace(/\/$/, "") === PROD_URL;
-}
-function profileNameForBaseUrl(baseUrl) {
-  return isProdBaseUrl(baseUrl) ? "prod" : "dev";
-}
-function projectEnvStartDir() {
-  return process.env.DEEPLINE_PROJECT_ENV_DIR?.trim() || process.cwd();
-}
+var PROJECT_DEEPLINE_ENV_FILE = ".env.deepline";
 function baseUrlSlug(baseUrl) {
   let url;
   try {
@@ -65,7 +58,7 @@ function baseUrlSlug(baseUrl) {
     return "unknown";
   }
   const host = url.hostname || "unknown";
-  const port = url.port ? parseInt(url.port, 10) : null;
+  const port = url.port ? Number.parseInt(url.port, 10) : null;
   let slug = host.replace(/[^a-zA-Z0-9]/g, "-");
   if (port && port !== 80 && port !== 443) {
     slug = `${slug}-${port}`;
@@ -92,79 +85,52 @@ function parseEnvFile(filePath) {
   }
   return env;
 }
-function findNearestEnvFile(names, startDir = process.cwd()) {
+function findNearestEnvFile(name, startDir = process.cwd()) {
   let current = resolve(startDir);
   while (true) {
-    for (const name of names) {
-      const filePath = join(current, name);
-      if (existsSync(filePath)) return filePath;
-    }
+    const filePath = join(current, name);
+    if (existsSync(filePath)) return filePath;
     const parent = dirname(current);
     if (parent === current) return null;
     current = parent;
   }
 }
-function findNearestEnv(names, startDir = process.cwd()) {
-  const filePath = findNearestEnvFile(names, startDir);
+function loadProjectDeeplineEnv(startDir = process.cwd()) {
+  const filePath = findNearestEnvFile(PROJECT_DEEPLINE_ENV_FILE, startDir);
   return filePath ? parseEnvFile(filePath) : {};
 }
-function findNearestWorktreeEnv(startDir = process.cwd()) {
-  return findNearestEnv([".env.worktree"], startDir);
-}
-function resolveProfileEnvFileNames() {
-  const explicitProfile = process.env.DEEPLINE_ENV_PROFILE?.trim() || process.env.DEEPLINE_PROFILE?.trim() || "";
-  const names = [];
-  if (explicitProfile) names.push(`.env.deepline.${explicitProfile}`);
-  const nodeEnv = process.env.NODE_ENV?.trim();
-  if (nodeEnv === "production") names.push(".env.deepline.prod");
-  else if (nodeEnv === "staging") names.push(".env.deepline.staging");
-  names.push(ACTIVE_DEEPLINE_ENV_FILE);
-  return names;
-}
-function resolveProjectAppEnvFileNames() {
-  const nodeEnv = process.env.NODE_ENV?.trim();
-  const names = [];
-  if (nodeEnv === "production") names.push(".env.prod");
-  if (nodeEnv === "staging") names.push(".env.staging");
-  names.push(".env.local", ".env");
-  return names;
-}
-function resolveBaseUrlFromEnvValues(env) {
-  return env.DEEPLINE_ORIGIN_URL?.trim() || env.DEEPLINE_API_BASE_URL?.trim() || "";
-}
-function loadProjectDeeplineEnv() {
-  return findNearestEnv(resolveProfileEnvFileNames(), projectEnvStartDir());
-}
-function loadProjectAppEnv() {
-  return findNearestEnv(resolveProjectAppEnvFileNames(), projectEnvStartDir());
-}
-function normalizeWorktreeBaseUrl(baseUrl, worktreeEnv = findNearestWorktreeEnv()) {
-  const trimmed = baseUrl.trim().replace(/\/$/, "");
-  if (!trimmed) return trimmed;
+function normalizeBaseUrl(baseUrl) {
+  const trimmed = baseUrl.trim().replace(/\/+$/, "");
+  if (!trimmed) return "";
   try {
     const parsed = new URL(trimmed);
-    if (parsed.hostname.endsWith(".localhost") && parsed.port === "1355") {
-      const port = worktreeEnv.WORKTREE_APP_PORT || worktreeEnv.PORT;
-      if (port) return `${parsed.protocol}//localhost:${port}`;
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return "";
     }
+    return parsed.toString().replace(/\/+$/, "");
   } catch {
+    return "";
   }
-  return trimmed;
 }
-function resolveWorktreeBaseUrl() {
-  const worktreeEnv = findNearestWorktreeEnv();
-  const declared = worktreeEnv.DEEPLINE_API_BASE_URL || worktreeEnv.WORKTREE_PUBLIC_APP_URL || worktreeEnv.APP_URL || "";
-  if (declared) return normalizeWorktreeBaseUrl(declared, worktreeEnv);
-  const port = worktreeEnv.WORKTREE_APP_PORT || worktreeEnv.PORT || "";
-  return port ? `http://localhost:${port}` : "";
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    const trimmed = value?.trim();
+    if (trimmed) return trimmed;
+  }
+  return "";
 }
-function sdkCliEnvFilePath(baseUrl) {
+function sdkCliConfigDir(baseUrl) {
   const home = process.env.HOME?.trim() || homedir();
-  return join(home, ".local", "deepline", baseUrlSlug(baseUrl || PROD_URL), ".env");
+  return join(home, ".local", "deepline", baseUrlSlug(baseUrl || PROD_URL));
+}
+function sdkCliEnvFilePath(baseUrl) {
+  return join(sdkCliConfigDir(baseUrl), ".env");
 }
 function loadCliEnv(baseUrl = PROD_URL) {
-  const envPath = sdkCliEnvFilePath(baseUrl);
-  return parseEnvFile(envPath);
+  return parseEnvFile(sdkCliEnvFilePath(baseUrl));
+}
+function hostConfigDirPath(baseUrl) {
+  return sdkCliConfigDir(baseUrl);
 }
 function hostEnvFilePath(baseUrl) {
   return sdkCliEnvFilePath(baseUrl);
@@ -175,9 +141,10 @@ function saveHostEnvValues(baseUrl, values) {
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }
-  const existing = existsSync(filePath) ? parseEnvFile(filePath) : {};
+  const existing = parseEnvFile(filePath);
   const merged = { ...existing, ...values };
-  const lines = Object.entries(merged).filter(([, value]) => value !== "").map(([key, value]) => `${key}=${value}`);
+  const allowedKeys = /* @__PURE__ */ new Set([HOST_URL_ENV, API_KEY_ENV]);
+  const lines = Object.entries(merged).filter(([key, value]) => allowedKeys.has(key) && value !== "").map(([key, value]) => `${key}=${value}`);
   writeFileSync(filePath, `${lines.join("\n")}
 `, "utf-8");
 }
@@ -185,31 +152,36 @@ function loadGlobalCliEnv() {
   return loadCliEnv(PROD_URL);
 }
 function autoDetectBaseUrl() {
-  const envOrigin = process.env.DEEPLINE_ORIGIN_URL?.trim();
-  if (envOrigin) return normalizeWorktreeBaseUrl(envOrigin);
-  const envBase = process.env.DEEPLINE_API_BASE_URL?.trim();
-  if (envBase) return normalizeWorktreeBaseUrl(envBase);
-  const projectDeeplineBaseUrl = resolveBaseUrlFromEnvValues(loadProjectDeeplineEnv());
-  if (projectDeeplineBaseUrl) return normalizeWorktreeBaseUrl(projectDeeplineBaseUrl);
-  const projectAppBaseUrl = resolveBaseUrlFromEnvValues(loadProjectAppEnv());
-  if (projectAppBaseUrl) return normalizeWorktreeBaseUrl(projectAppBaseUrl);
-  const worktreeBaseUrl = resolveWorktreeBaseUrl();
-  if (worktreeBaseUrl) return worktreeBaseUrl;
+  const projectEnv = loadProjectDeeplineEnv();
   const globalEnv = loadGlobalCliEnv();
-  const globalOrigin = globalEnv.DEEPLINE_ORIGIN_URL?.trim();
-  if (globalOrigin) return normalizeWorktreeBaseUrl(globalOrigin);
-  return PROD_URL;
+  return normalizeBaseUrl(process.env[HOST_URL_ENV] ?? "") || normalizeBaseUrl(projectEnv[HOST_URL_ENV] ?? "") || normalizeBaseUrl(globalEnv[HOST_URL_ENV] ?? "") || PROD_URL;
+}
+function resolveApiKeyForBaseUrl(baseUrl, explicitApiKey) {
+  const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
+  const projectEnv = loadProjectDeeplineEnv();
+  const cliEnv = loadCliEnv(normalizedBaseUrl || baseUrl);
+  const projectBaseUrl = normalizeBaseUrl(projectEnv[HOST_URL_ENV] ?? "");
+  const projectKeyApplies = projectBaseUrl === normalizedBaseUrl;
+  return firstNonEmpty(
+    explicitApiKey,
+    process.env[API_KEY_ENV],
+    projectKeyApplies ? projectEnv[API_KEY_ENV] : "",
+    cliEnv[API_KEY_ENV]
+  );
 }
 function resolveConfig(options) {
-  const requestedBaseUrl = options?.baseUrl?.trim() || autoDetectBaseUrl();
-  const baseUrl = normalizeWorktreeBaseUrl(requestedBaseUrl);
-  const cliEnv = loadCliEnv(baseUrl);
-  const projectDeeplineEnv = loadProjectDeeplineEnv();
-  const projectAppEnv = loadProjectAppEnv();
-  const apiKey = options?.apiKey?.trim() || process.env.DEEPLINE_API_KEY?.trim() || projectDeeplineEnv.DEEPLINE_API_KEY || projectAppEnv.DEEPLINE_API_KEY || cliEnv.DEEPLINE_API_KEY || "";
+  const baseUrl = normalizeBaseUrl(
+    options?.baseUrl?.trim() || autoDetectBaseUrl()
+  );
+  if (!baseUrl) {
+    throw new ConfigError(
+      `Invalid ${HOST_URL_ENV}. Expected an http(s) URL such as https://code.deepline.com.`
+    );
+  }
+  const apiKey = resolveApiKeyForBaseUrl(baseUrl, options?.apiKey);
   if (!apiKey) {
     throw new ConfigError(
-      `No API key found. Set DEEPLINE_API_KEY env var, pass apiKey option, or run: deepline auth register`
+      `No API key found. Set ${API_KEY_ENV}, add it to .env.deepline, or run: deepline auth register`
     );
   }
   return {
@@ -219,32 +191,10 @@ function resolveConfig(options) {
     maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES
   };
 }
-function mergeEnvFile(filePath, values) {
-  const existing = existsSync(filePath) ? parseEnvFile(filePath) : {};
-  const merged = { ...existing, ...values };
-  const dir = dirname(filePath);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  const lines = Object.entries(merged).filter(([, value]) => value !== "").map(([key, value]) => `${key}=${value}`);
-  writeFileSync(filePath, `${lines.join("\n")}
-`, "utf-8");
-}
-function saveProjectDeeplineEnvValues(baseUrl, values, startDir = projectEnvStartDir()) {
-  const root = resolve(startDir);
-  const profile = profileNameForBaseUrl(baseUrl);
-  const files = [
-    join(root, ACTIVE_DEEPLINE_ENV_FILE),
-    join(root, `.env.deepline.${profile}`)
-  ];
-  if (profile === "dev") files.push(join(root, ".env"));
-  for (const filePath of files) {
-    mergeEnvFile(filePath, values);
-  }
-  return files;
-}
 
 // src/version.ts
-var SDK_VERSION = "0.1.32";
-var SDK_API_CONTRACT = "2026-05-generic-play-input-flags";
+var SDK_VERSION = "0.1.35";
+var SDK_API_CONTRACT = "2026-05-v2-tool-result-contract";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
 var COORDINATOR_INTERNAL_TOKEN_HEADER = "x-deepline-internal-token";
@@ -326,7 +276,7 @@ var HttpClient = class {
           const response = await fetch(candidateUrl, {
             method,
             headers,
-            body: options?.formData !== void 0 ? options.formData : options?.body !== void 0 ? JSON.stringify(options.body) : void 0,
+            body: options?.formData !== void 0 ? typeof options.formData === "function" ? options.formData() : options.formData : options?.body !== void 0 ? JSON.stringify(options.body) : void 0,
             signal: controller.signal
           });
           clearTimeout(timeoutId);
@@ -409,10 +359,13 @@ var HttpClient = class {
           throw new AuthError();
         }
         if (!response.ok) {
+          const body = await response.text();
+          const parsed = parseResponseBody(body);
           throw new DeeplineError(
-            `HTTP ${response.status}`,
+            apiErrorMessage(parsed, response.status),
             response.status,
-            "API_ERROR"
+            "API_ERROR",
+            { response: parsed }
           );
         }
         if (!response.body) {
@@ -462,6 +415,26 @@ var HttpClient = class {
     return this.request(path, { method: "DELETE" });
   }
 };
+function parseResponseBody(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return body;
+  }
+}
+function apiErrorMessage(parsed, status) {
+  const errorValue = typeof parsed === "object" && parsed && "error" in parsed ? parsed.error : void 0;
+  if (typeof errorValue === "string") {
+    return errorValue;
+  }
+  if (errorValue && typeof errorValue === "object" && "message" in errorValue && typeof errorValue.message === "string") {
+    return errorValue.message;
+  }
+  if (typeof parsed === "object" && parsed && "message" in parsed && typeof parsed.message === "string") {
+    return parsed.message;
+  }
+  return `HTTP ${status}`;
+}
 function parseRetryAfter(response) {
   const header = response.headers.get("retry-after");
   if (header) {
@@ -525,15 +498,17 @@ function decodeSseFrame(frame) {
   return parsed;
 }
 function sleep(ms) {
-  return new Promise((resolve10) => setTimeout(resolve10, ms));
+  return new Promise((resolve11) => setTimeout(resolve11, ms));
 }
 
 // src/client.ts
 var TERMINAL_PLAY_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
 var INCLUDE_TOOL_METADATA_HEADER = "x-deepline-include-tool-metadata";
+var EXECUTE_RESPONSE_CONTRACT_HEADER = "x-deepline-execute-response-contract";
+var V2_EXECUTE_RESPONSE_CONTRACT = "v2-tool-execution-result";
 var COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1e3];
 function sleep2(ms) {
-  return new Promise((resolve10) => setTimeout(resolve10, ms));
+  return new Promise((resolve11) => setTimeout(resolve11, ms));
 }
 function isTransientCompileManifestError(error) {
   if (error instanceof DeeplineError && typeof error.statusCode === "number") {
@@ -799,13 +774,16 @@ var DeeplineClient = class {
   /**
    * Execute a tool and return the standard execution envelope.
    *
-   * The `result.data` field contains the provider payload. `result.meta`
-   * contains provider/upstream metadata such as HTTP status or paging details.
+   * The `toolExecutionResult.toolOutput.raw` field contains the raw tool output.
+   * `toolExecutionResult.toolOutput.meta` contains tool/provider metadata.
    * Top-level fields such as `status`, `job_id`, and `billing` describe the
-   * Deepline execution.
+   * Deepline execution envelope.
    */
   async executeTool(toolId, input, options) {
-    const headers = options?.includeToolMetadata ? { [INCLUDE_TOOL_METADATA_HEADER]: "true" } : void 0;
+    const headers = {
+      [EXECUTE_RESPONSE_CONTRACT_HEADER]: V2_EXECUTE_RESPONSE_CONTRACT,
+      ...options?.includeToolMetadata ? { [INCLUDE_TOOL_METADATA_HEADER]: "true" } : {}
+    };
     return this.http.post(
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
       { payload: input },
@@ -1103,34 +1081,37 @@ var DeeplineClient = class {
    * ```
    */
   async stagePlayFiles(files) {
-    const formData = new FormData();
-    formData.set(
-      "metadata",
-      JSON.stringify({
-        files: files.map((file, index) => ({
-          index,
-          logicalPath: file.logicalPath,
-          contentHash: file.contentHash,
-          contentType: file.contentType,
-          bytes: file.bytes
-        }))
-      })
-    );
-    for (const [index, file] of files.entries()) {
-      const bytes = decodeBase64Bytes(file.contentBase64);
-      const body = bytes.buffer.slice(
-        bytes.byteOffset,
-        bytes.byteOffset + bytes.byteLength
-      );
+    const buildFormData = () => {
+      const formData = new FormData();
       formData.set(
-        `file:${index}`,
-        new Blob([body], { type: file.contentType }),
-        file.logicalPath
+        "metadata",
+        JSON.stringify({
+          files: files.map((file, index) => ({
+            index,
+            logicalPath: file.logicalPath,
+            contentHash: file.contentHash,
+            contentType: file.contentType,
+            bytes: file.bytes
+          }))
+        })
       );
-    }
+      for (const [index, file] of files.entries()) {
+        const bytes = decodeBase64Bytes(file.contentBase64);
+        const body = bytes.buffer.slice(
+          bytes.byteOffset,
+          bytes.byteOffset + bytes.byteLength
+        );
+        formData.set(
+          `file:${index}`,
+          new Blob([body], { type: file.contentType }),
+          file.logicalPath
+        );
+      }
+      return formData;
+    };
     const response = await this.http.postFormData(
       "/api/v2/plays/files/stage",
-      formData
+      buildFormData
     );
     return response.files;
   }
@@ -1654,7 +1635,7 @@ async function enforceSdkCompatibility(baseUrl) {
 }
 
 // src/cli/commands/auth.ts
-import { writeFileSync as writeFileSync3, existsSync as existsSync3, mkdirSync as mkdirSync3 } from "fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, rmSync, writeFileSync as writeFileSync3 } from "fs";
 import { hostname } from "os";
 import { dirname as dirname3 } from "path";
 
@@ -1668,10 +1649,11 @@ import {
 import { mkdir, writeFile } from "fs/promises";
 import { homedir as homedir2 } from "os";
 import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
-import { execFileSync, spawnSync } from "child_process";
+import * as childProcess from "child_process";
 import { parse } from "csv-parse/sync";
 import { stringify } from "csv-stringify/sync";
 var BROWSER_FOCUS_COOLDOWN_MS = 3e4;
+var defaultBrowserCommandRunner = childProcess;
 function getAuthedHttpClient() {
   const config = resolveConfig();
   return { config, http: new HttpClient(config) };
@@ -1740,9 +1722,9 @@ function browserAppNameFromBundleId(bundleId) {
   };
   return names[bundleId.toLowerCase()] ?? "";
 }
-function readDefaultMacBrowserBundleId() {
+function readDefaultMacBrowserBundleId(runner = defaultBrowserCommandRunner) {
   try {
-    const output = execFileSync(
+    const output = runner.execFileSync(
       "/usr/bin/defaults",
       [
         "read",
@@ -1778,8 +1760,8 @@ function browserStrategyForBundleId(bundleId) {
   }
   return normalized === "com.apple.safari" ? "safari" : "fallback";
 }
-function runAppleScript(script, args) {
-  const result = spawnSync("osascript", ["-", ...args], {
+function runAppleScript(script, args, runner = defaultBrowserCommandRunner) {
+  const result = runner.spawnSync("osascript", ["-", ...args], {
     input: script,
     encoding: "utf-8",
     stdio: ["pipe", "ignore", "ignore"],
@@ -1787,7 +1769,7 @@ function runAppleScript(script, args) {
   });
   return result.status === 0;
 }
-function retargetChromiumMacos(appName, targetUrl, allowFocus) {
+function retargetChromiumMacos(appName, targetUrl, allowFocus, runner = defaultBrowserCommandRunner) {
   const host = extractUrlHost(targetUrl);
   if (!host) return false;
   const escapedAppName = appName.replace(/"/g, '\\"');
@@ -1819,9 +1801,9 @@ ${newTabBlock}    end if
   end tell
 end run
 `;
-  return runAppleScript(script, [targetUrl, host]);
+  return runAppleScript(script, [targetUrl, host], runner);
 }
-function retargetSafariMacos(appName, targetUrl, allowFocus) {
+function retargetSafariMacos(appName, targetUrl, allowFocus, runner = defaultBrowserCommandRunner) {
   const host = extractUrlHost(targetUrl);
   if (!host) return false;
   const escapedAppName = appName.replace(/"/g, '\\"');
@@ -1853,30 +1835,38 @@ ${newTabBlock}    end if
   end tell
 end run
 `;
-  return runAppleScript(script, [targetUrl, host]);
+  return runAppleScript(script, [targetUrl, host], runner);
 }
-function openUrlMacos(targetUrl, allowFocus) {
-  const defaultBundleId = readDefaultMacBrowserBundleId();
+function openUrlMacos(targetUrl, allowFocus, runner = defaultBrowserCommandRunner) {
+  const defaultBundleId = readDefaultMacBrowserBundleId(runner);
   const appName = defaultBundleId ? browserAppNameFromBundleId(defaultBundleId) : "";
   const strategy = browserStrategyForBundleId(defaultBundleId);
-  if (appName && strategy === "chromium" && retargetChromiumMacos(appName, targetUrl, allowFocus)) {
+  if (appName && strategy === "chromium" && retargetChromiumMacos(appName, targetUrl, allowFocus, runner)) {
     return true;
   }
-  if (appName && strategy === "safari" && retargetSafariMacos(appName, targetUrl, allowFocus)) {
+  if (appName && strategy === "safari" && retargetSafariMacos(appName, targetUrl, allowFocus, runner)) {
     return true;
   }
-  if (!allowFocus) {
-    return false;
-  }
   try {
-    execFileSync("open", [targetUrl], { stdio: "ignore" });
+    runner.execFileSync(
+      "open",
+      [...allowFocus ? [] : ["-g"], targetUrl],
+      { stdio: "ignore" }
+    );
     return true;
   } catch {
     return false;
   }
 }
+function browserOpeningDisabled() {
+  const value = String(
+    process.env.DEEPLINE_NO_BROWSER ?? process.env.PLAYGROUND_HEADLESS ?? ""
+  ).trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes" || value === "on";
+}
 function openInBrowser(url) {
   try {
+    if (browserOpeningDisabled()) return;
     const targetUrl = String(url || "").trim();
     if (!targetUrl) return;
     const allowFocus = claimBrowserFocus();
@@ -1886,12 +1876,12 @@ function openInBrowser(url) {
     }
     if (!allowFocus) return;
     if (process.platform === "win32") {
-      execFileSync("cmd.exe", ["/c", "start", "", targetUrl], {
+      childProcess.execFileSync("cmd.exe", ["/c", "start", "", targetUrl], {
         stdio: "ignore"
       });
       return;
     }
-    execFileSync("xdg-open", [targetUrl], { stdio: "ignore" });
+    childProcess.execFileSync("xdg-open", [targetUrl], { stdio: "ignore" });
   } catch {
   }
 }
@@ -1915,6 +1905,103 @@ function csvStringFromRows(rows, columns) {
     ...columns?.length ? { columns } : {}
   });
 }
+function parseMaybeJsonObject(value) {
+  if (typeof value !== "string") {
+    return value;
+  }
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) {
+    return value;
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return value;
+  }
+}
+function flattenObjectColumns(row) {
+  const flattened = {};
+  for (const [key, rawValue] of Object.entries(row)) {
+    const value = parseMaybeJsonObject(rawValue);
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      for (const [nestedKey, nestedValue] of Object.entries(
+        value
+      )) {
+        flattened[`${key}.${nestedKey}`] = nestedValue && typeof nestedValue === "object" ? JSON.stringify(nestedValue) : nestedValue;
+      }
+      continue;
+    }
+    flattened[key] = Array.isArray(value) ? JSON.stringify(value) : value;
+  }
+  return flattened;
+}
+function recordRows(value) {
+  return value.filter(
+    (row) => Boolean(row) && typeof row === "object" && !Array.isArray(row)
+  );
+}
+function dataExportRows(rows) {
+  return rows.map((row) => flattenObjectColumns(row));
+}
+function dataExportColumns(rows, preferredColumns = []) {
+  const discoveredColumns = [
+    ...new Set(rows.flatMap((row) => Object.keys(row)))
+  ];
+  if (rows.length === 0) {
+    return [...new Set(preferredColumns.filter(Boolean))];
+  }
+  const discovered = new Set(discoveredColumns);
+  const columns = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const column of preferredColumns) {
+    if (!column) {
+      continue;
+    }
+    const expandedColumns = discovered.has(column) ? [column] : discoveredColumns.filter(
+      (discoveredColumn) => discoveredColumn.startsWith(`${column}.`)
+    );
+    for (const expandedColumn of expandedColumns) {
+      if (seen.has(expandedColumn)) {
+        continue;
+      }
+      seen.add(expandedColumn);
+      columns.push(expandedColumn);
+    }
+  }
+  for (const column of discoveredColumns) {
+    if (seen.has(column)) {
+      continue;
+    }
+    seen.add(column);
+    columns.push(column);
+  }
+  return columns;
+}
+function dataExportCsvString(rows, preferredColumns = []) {
+  const flattenedRows = dataExportRows(rows);
+  return csvStringFromRows(
+    flattenedRows,
+    dataExportColumns(flattenedRows, preferredColumns)
+  );
+}
+function markdownCell(value) {
+  if (value === null || value === void 0) {
+    return "";
+  }
+  const text = typeof value === "object" ? JSON.stringify(value) : String(value);
+  return text.replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>");
+}
+function markdownTableFromRows(rows, preferredColumns = []) {
+  const flattenedRows = dataExportRows(rows);
+  const columns = dataExportColumns(flattenedRows, preferredColumns);
+  const header = `| ${columns.map(markdownCell).join(" | ")} |`;
+  const separator = `| ${columns.map(() => "---").join(" | ")} |`;
+  const body = flattenedRows.map(
+    (row) => `| ${columns.map((column) => markdownCell(row[column])).join(" | ")} |`
+  );
+  return `${[header, separator, ...body].join("\n")}
+`;
+}
 function printJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}
 `);
@@ -2005,17 +2092,39 @@ var EXIT_SERVER = 2;
 function envFilePath(baseUrl) {
   return hostEnvFilePath(baseUrl);
 }
-function saveEnvValues(values, baseUrl) {
-  const filePath = envFilePath(baseUrl);
+function pendingClaimTokenPath(baseUrl) {
+  return `${hostConfigDirPath(baseUrl)}/pending-claim-token`;
+}
+function savePendingClaimToken(baseUrl, claimToken) {
+  const filePath = pendingClaimTokenPath(baseUrl);
   const dir = dirname3(filePath);
   if (!existsSync3(dir)) {
     mkdirSync3(dir, { recursive: true });
   }
-  const existing = existsSync3(filePath) ? parseEnvFile(filePath) : {};
-  const merged = { ...existing, ...values };
-  const lines = Object.entries(merged).filter(([, v]) => v !== "").map(([k, v]) => `${k}=${v}`);
-  writeFileSync3(filePath, lines.join("\n") + "\n", "utf-8");
-  saveProjectDeeplineEnvValues(baseUrl, values);
+  writeFileSync3(filePath, `${claimToken}
+`, "utf-8");
+}
+function readPendingClaimToken(baseUrl) {
+  const filePath = pendingClaimTokenPath(baseUrl);
+  if (!existsSync3(filePath)) return "";
+  try {
+    return readFileSync3(filePath, "utf-8").trim();
+  } catch {
+    return "";
+  }
+}
+function clearPendingClaimToken(baseUrl) {
+  try {
+    rmSync(pendingClaimTokenPath(baseUrl), { force: true });
+  } catch {
+  }
+}
+function saveEnvValues(values, baseUrl) {
+  const filtered = {
+    ...values[HOST_URL_ENV] ? { [HOST_URL_ENV]: values[HOST_URL_ENV] } : {},
+    ...values[API_KEY_ENV] ? { [API_KEY_ENV]: values[API_KEY_ENV] } : {}
+  };
+  saveHostEnvValues(baseUrl, filtered);
 }
 async function httpJson(method, url, apiKey, body) {
   const headers = { "Content-Type": "application/json" };
@@ -2069,7 +2178,7 @@ function buildCandidateUrls2(url) {
   }
 }
 function sleep3(ms) {
-  return new Promise((resolve10) => setTimeout(resolve10, ms));
+  return new Promise((resolve11) => setTimeout(resolve11, ms));
 }
 function printDeeplineLogo() {
   if (process.stdout.isTTY && (process.stdout.columns ?? 80) >= 70) {
@@ -2121,9 +2230,9 @@ async function handleRegister(args) {
   const claimUrl = String(data.claim_url || "");
   const claimToken = String(data.claim_token || "");
   if (claimToken) {
+    savePendingClaimToken(baseUrl, claimToken);
     saveEnvValues({
-      DEEPLINE_ORIGIN_URL: baseUrl,
-      DEEPLINE_CLAIM_TOKEN: claimToken
+      [HOST_URL_ENV]: baseUrl
     }, baseUrl);
   }
   if (claimUrl) {
@@ -2147,6 +2256,7 @@ async function handleRegister(args) {
       { claim_token: claimToken, reveal: true }
     );
     if (s === 401 || s === 403) {
+      clearPendingClaimToken(baseUrl);
       console.log("Status: unauthorized");
       return EXIT_AUTH;
     }
@@ -2163,15 +2273,16 @@ async function handleRegister(args) {
       const apiKey = String(statusData.api_key || "");
       if (apiKey) {
         saveEnvValues({
-          DEEPLINE_ORIGIN_URL: baseUrl,
-          DEEPLINE_API_KEY: apiKey,
-          DEEPLINE_CLAIM_TOKEN: ""
+          [HOST_URL_ENV]: baseUrl,
+          [API_KEY_ENV]: apiKey
         }, baseUrl);
+        clearPendingClaimToken(baseUrl);
         printClaimSuccessBanner(statusData);
         return EXIT_OK;
       }
     }
     if (state === "expired") {
+      clearPendingClaimToken(baseUrl);
       console.log("That approval link expired. Please run: deepline auth register");
       return EXIT_AUTH;
     }
@@ -2189,13 +2300,12 @@ async function handleWait(args) {
       }
     }
   }
-  const env = loadCliEnv(baseUrl);
-  if (env.DEEPLINE_API_KEY?.trim()) {
-    console.log("Already connected.");
-    return EXIT_OK;
-  }
-  const claimToken = env.DEEPLINE_CLAIM_TOKEN?.trim() || "";
+  const claimToken = readPendingClaimToken(baseUrl);
   if (!claimToken) {
+    if (resolveApiKeyForBaseUrl(baseUrl)) {
+      console.log("Already connected.");
+      return EXIT_OK;
+    }
     console.error("No pending approval. Run: deepline auth register --no-wait");
     return EXIT_AUTH;
   }
@@ -2208,6 +2318,7 @@ async function handleWait(args) {
       { claim_token: claimToken, reveal: true }
     );
     if (status === 401 || status === 403) {
+      clearPendingClaimToken(baseUrl);
       console.error("Claim is invalid. Run: deepline auth register");
       return EXIT_AUTH;
     }
@@ -2224,15 +2335,16 @@ async function handleWait(args) {
       const apiKey = String(data.api_key || "");
       if (apiKey) {
         saveEnvValues({
-          DEEPLINE_ORIGIN_URL: baseUrl,
-          DEEPLINE_API_KEY: apiKey,
-          DEEPLINE_CLAIM_TOKEN: ""
+          [HOST_URL_ENV]: baseUrl,
+          [API_KEY_ENV]: apiKey
         }, baseUrl);
+        clearPendingClaimToken(baseUrl);
         printClaimSuccessBanner(data);
         return EXIT_OK;
       }
     }
     if (state === "expired") {
+      clearPendingClaimToken(baseUrl);
       console.error("That approval link expired. Run: deepline auth register");
       return EXIT_AUTH;
     }
@@ -2267,10 +2379,9 @@ async function handleStatus(args) {
     };
     hostLines.push(`Host: ${baseUrl} (unreachable)`);
   }
-  const env = loadCliEnv(baseUrl);
-  const apiKey = process.env.DEEPLINE_API_KEY?.trim() || env.DEEPLINE_API_KEY || "";
+  const apiKey = resolveApiKeyForBaseUrl(baseUrl);
   if (!apiKey) {
-    if (env.DEEPLINE_CLAIM_TOKEN?.trim()) {
+    if (readPendingClaimToken(baseUrl)) {
       printCommandEnvelope({
         ...hostStatusPayload ?? { host: baseUrl },
         status: "pending",
@@ -2316,6 +2427,7 @@ async function handleStatus(args) {
     console.error(`Auth status error (status ${status}).`);
     return EXIT_SERVER;
   }
+  clearPendingClaimToken(baseUrl);
   const payload = {
     ...hostStatusPayload ?? { host: baseUrl },
     status: data.status || "(unknown)",
@@ -2336,9 +2448,8 @@ async function handleStatus(args) {
     const apiKeyResp = String(data.api_key || apiKey);
     if (apiKeyResp) {
       saveEnvValues({
-        DEEPLINE_ORIGIN_URL: baseUrl,
-        DEEPLINE_API_KEY: apiKeyResp,
-        DEEPLINE_CLAIM_TOKEN: ""
+        [HOST_URL_ENV]: baseUrl,
+        [API_KEY_ENV]: apiKeyResp
       }, baseUrl);
       savedApiKeyPath = envFilePath(baseUrl);
     }
@@ -3267,10 +3378,12 @@ function writeCanonicalRowsCsv(rowsInfo, outPath) {
     rows: rowsInfo.rows,
     columns: rowsInfo.columns
   });
+  const rows = dataExportRows(sanitized.rows);
+  const columns = dataExportColumns(rows, sanitized.columns);
   const resolved = resolve4(outPath);
   writeFileSync4(
     resolved,
-    csvStringFromRows(sanitized.rows, sanitized.columns),
+    csvStringFromRows(rows, columns),
     "utf-8"
   );
   return resolved;
@@ -3391,6 +3504,14 @@ Examples:
 }
 
 // src/cli/commands/db.ts
+import { writeFileSync as writeFileSync5 } from "fs";
+import { resolve as resolve5 } from "path";
+var CUSTOMER_DB_QUERY_FORMATS = /* @__PURE__ */ new Set([
+  "table",
+  "json",
+  "csv",
+  "markdown"
+]);
 function parsePositiveInteger(value, flagName) {
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed) || parsed <= 0) {
@@ -3404,10 +3525,8 @@ function formatCell(value) {
   return text.length > 80 ? `${text.slice(0, 77)}...` : text;
 }
 function tableLines(result) {
-  const rows = result.rows.filter(
-    (row) => Boolean(row) && typeof row === "object" && !Array.isArray(row)
-  );
-  const responseColumns = result.columns.length > 0 ? result.columns.map((column) => column.name) : [...new Set(rows.flatMap((row) => Object.keys(row)))];
+  const rows = dataExportRows(customerDbRows(result));
+  const responseColumns = dataExportColumns(rows, customerDbColumnNames(result));
   const businessColumns = responseColumns.filter((column) => !column.startsWith("_"));
   const columns = businessColumns.length > 0 ? businessColumns : responseColumns;
   const hiddenColumns = responseColumns.filter((column) => !columns.includes(column));
@@ -3441,22 +3560,146 @@ function tableLines(result) {
   }
   return lines;
 }
+function customerDbRows(result) {
+  return recordRows(result.rows);
+}
+function customerDbColumnNames(result) {
+  return result.columns.map((column) => column.name).filter(Boolean);
+}
+function writeCustomerDbCsv(result, outPath) {
+  const resolved = resolve5(outPath);
+  writeFileSync5(
+    resolved,
+    dataExportCsvString(customerDbRows(result), customerDbColumnNames(result)),
+    "utf-8"
+  );
+  return resolved;
+}
+function dbQueryExportEnvelope(input) {
+  const destination = input.outPath ?? "stdout";
+  return {
+    command: input.result.command,
+    format: input.format,
+    row_count: input.result.row_count,
+    row_count_returned: input.result.row_count_returned,
+    truncated: input.result.truncated,
+    ...input.outPath ? { file: input.outPath, local: { file: input.outPath } } : {},
+    next: { toolEquivalent: input.toolCommand },
+    render: {
+      sections: [
+        {
+          title: "customer db export",
+          lines: [
+            `Rendered ${input.result.row_count_returned} row(s) as ${input.format} to ${destination}`
+          ]
+        }
+      ],
+      actions: [{ label: "Tool equivalent", command: input.toolCommand }]
+    }
+  };
+}
 async function handleDbQuery(args) {
   const sqlIndex = args.indexOf("--sql");
   const sql = sqlIndex >= 0 ? args[sqlIndex + 1]?.trim() : "";
   if (!sql) {
-    console.error('Usage: deepline db query --sql "select * from table limit 20" [--max-rows N] [--json]');
+    console.error(
+      'Usage: deepline db query --sql "select * from table limit 20" [--max-rows N] [--json]'
+    );
     return 1;
   }
   const maxRowsIndex = args.indexOf("--max-rows");
   const maxRows = maxRowsIndex >= 0 && args[maxRowsIndex + 1] ? parsePositiveInteger(args[maxRowsIndex + 1], "--max-rows") : void 0;
+  const formatIndex = args.indexOf("--format");
+  const format = formatIndex >= 0 ? args[formatIndex + 1]?.trim().toLowerCase() : "";
+  if (format && !CUSTOMER_DB_QUERY_FORMATS.has(format)) {
+    console.error(
+      'Usage: deepline db query --sql "select * from table limit 20" [--format table|json|csv|markdown] [--out path]'
+    );
+    return 1;
+  }
+  const outIndex = args.indexOf("--out");
+  const outPath = outIndex >= 0 ? args[outIndex + 1]?.trim() : "";
+  if (outIndex >= 0 && !outPath) {
+    console.error("--out requires a path.");
+    return 1;
+  }
   const jsonOutput = argsWantJson(args);
+  const explicitJsonOutput = args.includes("--json");
   const client = new DeeplineClient();
   const result = await client.queryCustomerDb({ sql, maxRows });
   const toolCommand = `deepline tools execute query_customer_db --payload ${JSON.stringify({
     sql,
     ...maxRows ? { max_rows: maxRows } : {}
   })} --json`;
+  if (format === "csv") {
+    if (outPath) {
+      const exportedPath = writeCustomerDbCsv(result, outPath);
+      printCommandEnvelope(
+        dbQueryExportEnvelope({
+          result,
+          format,
+          outPath: exportedPath,
+          toolCommand
+        }),
+        {
+          json: jsonOutput,
+          text: `Exported ${result.row_count_returned} row(s) to ${exportedPath}
+`
+        }
+      );
+      return 0;
+    }
+    printCommandEnvelope(
+      dbQueryExportEnvelope({
+        result,
+        format,
+        outPath: null,
+        toolCommand
+      }),
+      {
+        json: explicitJsonOutput,
+        text: dataExportCsvString(customerDbRows(result), customerDbColumnNames(result))
+      }
+    );
+    return 0;
+  }
+  if (format === "markdown") {
+    const content = markdownTableFromRows(
+      customerDbRows(result),
+      customerDbColumnNames(result)
+    );
+    if (outPath) {
+      const exportedPath = resolve5(outPath);
+      writeFileSync5(exportedPath, content, "utf-8");
+      printCommandEnvelope(
+        dbQueryExportEnvelope({
+          result,
+          format,
+          outPath: exportedPath,
+          toolCommand
+        }),
+        {
+          json: jsonOutput,
+          text: `Exported ${result.row_count_returned} row(s) to ${exportedPath}
+`
+        }
+      );
+      return 0;
+    }
+    printCommandEnvelope(
+      dbQueryExportEnvelope({
+        result,
+        format,
+        outPath: null,
+        toolCommand
+      }),
+      {
+        json: explicitJsonOutput,
+        text: content
+      }
+    );
+    return 0;
+  }
   printCommandEnvelope({
     ...result,
     next: { toolEquivalent: toolCommand },
@@ -3464,7 +3707,7 @@ async function handleDbQuery(args) {
       sections: [{ title: "customer db query", lines: tableLines(result) }],
       actions: [{ label: "Tool equivalent", command: toolCommand }]
     }
-  }, { json: jsonOutput });
+  }, { json: jsonOutput || format === "json" });
   return 0;
 }
 function registerDbCommands(program) {
@@ -3474,11 +3717,14 @@ function registerDbCommands(program) {
 Notes:
   Runs SQL against the active workspace customer database through Deepline APIs.
   Results are bounded by the server and --max-rows. Use --json for stable output.
+  Use --format csv or --format markdown for agent-readable exports and display tables.
 
 Examples:
   deepline db query --sql "select * from companies limit 20"
   deepline db query --sql "select domain, name from companies limit 20" --json
   deepline db query --sql "select * from contacts" --max-rows 100 --json
+  deepline db query --sql "select * from contacts limit 20" --format csv --out contacts.csv
+  deepline db query --sql "select domain, name from companies limit 20" --format markdown
 `
   );
   db.command("query").alias("psql").description("Run SQL against the tenant customer database.").addHelpText(
@@ -3487,17 +3733,23 @@ Examples:
 Notes:
   Requires --sql. Output is a compact table in a terminal and raw JSON with
   --json or when stdout is piped. The active auth workspace determines scope.
+  --format csv and --format markdown are explicit data/display formats and can
+  be written directly with --out.
 
 Examples:
   deepline db query --sql "select * from companies limit 20"
   deepline db query --sql "select domain, name from companies limit 20" --json
   deepline db psql --sql "select count(*) from contacts" --json
+  deepline db query --sql "select * from contacts limit 20" --format csv --out contacts.csv
+  deepline db query --sql "select domain, name from companies limit 20" --format markdown
 `
-  ).requiredOption("--sql <sql>", "SQL statement").option("--max-rows <n>", "Maximum returned rows").option("--json", "Emit raw JSON response. Also automatic when stdout is piped").action(async (options) => {
+  ).requiredOption("--sql <sql>", "SQL statement").option("--max-rows <n>", "Maximum returned rows").option("--format <format>", "Output format: table, json, csv, or markdown").option("--out <path>", "Write csv or markdown output to a file").option("--json", "Emit raw JSON response. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handleDbQuery([
       "--sql",
       options.sql,
       ...options.maxRows ? ["--max-rows", options.maxRows] : [],
+      ...options.format ? ["--format", options.format] : [],
+      ...options.out ? ["--out", options.out] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
@@ -3675,25 +3927,25 @@ Examples:
 import { createHash as createHash3 } from "crypto";
 import {
   existsSync as existsSync6,
-  readFileSync as readFileSync4,
+  readFileSync as readFileSync5,
   readdirSync,
   realpathSync,
-  writeFileSync as writeFileSync5
+  writeFileSync as writeFileSync6
 } from "fs";
-import { basename as basename3, dirname as dirname8, join as join6, resolve as resolve8 } from "path";
+import { basename as basename3, dirname as dirname8, join as join6, resolve as resolve9 } from "path";
 
 // src/plays/bundle-play-file.ts
 import { tmpdir as tmpdir2 } from "os";
-import { dirname as dirname7, join as join5, resolve as resolve7 } from "path";
+import { dirname as dirname7, join as join5, resolve as resolve8 } from "path";
 import { fileURLToPath } from "url";
 import { existsSync as existsSync5 } from "fs";
 
 // ../shared_libs/plays/bundling/index.ts
 import { createHash } from "crypto";
-import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
 import { mkdir as mkdir3, readFile, realpath, stat, writeFile as writeFile3 } from "fs/promises";
 import { tmpdir } from "os";
-import { basename, dirname as dirname5, extname, isAbsolute, join as join3, resolve as resolve5 } from "path";
+import { basename, dirname as dirname5, extname, isAbsolute, join as join3, resolve as resolve6 } from "path";
 import { builtinModules } from "module";
 import { build } from "esbuild";
 
@@ -3785,7 +4037,7 @@ async function normalizeLocalPath(filePath) {
   try {
     return await realpath(filePath);
   } catch {
-    return resolve5(filePath);
+    return resolve6(filePath);
   }
 }
 function createPlayWorkspace(entryFile) {
@@ -3944,7 +4196,7 @@ function extractDefinedPlayName(sourceCode) {
 }
 function readPackageVersionFromPackageJson(packageJsonPath, packageName) {
   try {
-    const packageJson = JSON.parse(readFileSync3(packageJsonPath, "utf-8"));
+    const packageJson = JSON.parse(readFileSync4(packageJsonPath, "utf-8"));
     if (packageJson.name === packageName && typeof packageJson.version === "string") {
       return packageJson.version;
     }
@@ -3954,7 +4206,7 @@ function readPackageVersionFromPackageJson(packageJsonPath, packageName) {
   return null;
 }
 function findPackageJsonPathFrom(startDir, packageName) {
-  let current = resolve5(startDir);
+  let current = resolve6(startDir);
   while (true) {
     const packageJsonPath = join3(
       current,
@@ -3981,7 +4233,7 @@ function findPackageJsonPath(packageName, fromFile, adapter) {
   ];
   const seen = /* @__PURE__ */ new Set();
   for (const startDir of startDirs) {
-    const normalized = resolve5(startDir);
+    const normalized = resolve6(startDir);
     if (seen.has(normalized)) continue;
     seen.add(normalized);
     const packageJsonPath = findPackageJsonPathFrom(normalized, packageName);
@@ -4218,7 +4470,7 @@ async function resolveLocalImport(fromFile, specifier) {
   if (specifier.startsWith("file:")) {
     return normalizeLocalPath(new URL(specifier).pathname);
   }
-  const base = isAbsolute(specifier) ? resolve5(specifier) : resolve5(dirname5(fromFile), specifier);
+  const base = isAbsolute(specifier) ? resolve6(specifier) : resolve6(dirname5(fromFile), specifier);
   const candidates = [base];
   const explicitExtension = extname(base).toLowerCase();
   if (!explicitExtension) {
@@ -4239,7 +4491,7 @@ function resolvePackageImport(specifier, fromFile, adapter) {
   const packageName = getPackageName(specifier);
   if (packageName === "deepline" && existsSync4(adapter.sdkPackageJson)) {
     const packageJson = JSON.parse(
-      readFileSync3(adapter.sdkPackageJson, "utf-8")
+      readFileSync4(adapter.sdkPackageJson, "utf-8")
     );
     return {
       name: "deepline",
@@ -4416,7 +4668,7 @@ function normalizeSourceMapForRuntime(sourceMapText) {
     if (sourcePath.startsWith("data:") || sourcePath.startsWith("node:") || sourcePath.startsWith("/") || /^[a-zA-Z]+:\/\//.test(sourcePath)) {
       return sourcePath;
     }
-    return resolve5(process.cwd(), sourcePath);
+    return resolve6(process.cwd(), sourcePath);
   });
   parsed.sourceRoot = void 0;
   return JSON.stringify(parsed);
@@ -4738,7 +4990,7 @@ function resolveExecutionProfile(override) {
 // src/plays/local-file-discovery.ts
 import { createHash as createHash2 } from "crypto";
 import { readFile as readFile2, stat as stat2 } from "fs/promises";
-import { basename as basename2, dirname as dirname6, extname as extname2, isAbsolute as isAbsolute2, join as join4, relative, resolve as resolve6 } from "path";
+import { basename as basename2, dirname as dirname6, extname as extname2, isAbsolute as isAbsolute2, join as join4, relative, resolve as resolve7 } from "path";
 var SOURCE_EXTENSIONS2 = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs", ".json"];
 function sha2562(buffer) {
   return createHash2("sha256").update(buffer).digest("hex");
@@ -4939,7 +5191,7 @@ function isPathInsideDirectory2(filePath, directory) {
   return relativePath === "" || !relativePath.startsWith("..") && !isAbsolute2(relativePath);
 }
 async function resolveLocalImport2(fromFile, specifier) {
-  const base = isAbsolute2(specifier) ? resolve6(specifier) : resolve6(dirname6(fromFile), specifier);
+  const base = isAbsolute2(specifier) ? resolve7(specifier) : resolve7(dirname6(fromFile), specifier);
   const candidates = [base];
   const explicitExtension = extname2(base).toLowerCase();
   if (!explicitExtension) {
@@ -4957,13 +5209,13 @@ async function resolveLocalImport2(fromFile, specifier) {
   throw new Error(`Could not resolve local import "${specifier}" from ${fromFile}`);
 }
 async function discoverPackagedLocalFiles(entryFile) {
-  const absoluteEntryFile = resolve6(entryFile);
+  const absoluteEntryFile = resolve7(entryFile);
   const packagingRoot = dirname6(absoluteEntryFile);
   const files = /* @__PURE__ */ new Map();
   const unresolved = [];
   const visitedFiles = /* @__PURE__ */ new Set();
   const visitSourceFile = async (filePath) => {
-    const absolutePath = resolve6(filePath);
+    const absolutePath = resolve7(filePath);
     if (visitedFiles.has(absolutePath)) {
       return;
     }
@@ -4995,7 +5247,7 @@ async function discoverPackagedLocalFiles(entryFile) {
             message: "Could not resolve this ctx.csv(...) path at submit time. Use a string literal, a top-level const string, or pass a runtime input like input.file."
           });
         } else {
-          const absoluteCsvPath = resolve6(dirname6(absolutePath), resolvedPath);
+          const absoluteCsvPath = resolve7(dirname6(absolutePath), resolvedPath);
           if (isAbsolute2(resolvedPath) || !isPathInsideDirectory2(absoluteCsvPath, packagingRoot)) {
             unresolved.push({
               sourceFragment: sourceCode.slice(argument.start, argument.end).trim(),
@@ -5035,23 +5287,23 @@ async function discoverPackagedLocalFiles(entryFile) {
 // src/plays/bundle-play-file.ts
 var PLAY_BUNDLE_CACHE_VERSION2 = 30;
 var MODULE_DIR = dirname7(fileURLToPath(import.meta.url));
-var SDK_PACKAGE_ROOT = resolve7(MODULE_DIR, "..", "..");
-var SOURCE_REPO_ROOT = resolve7(SDK_PACKAGE_ROOT, "..");
+var SDK_PACKAGE_ROOT = resolve8(MODULE_DIR, "..", "..");
+var SOURCE_REPO_ROOT = resolve8(SDK_PACKAGE_ROOT, "..");
 var HAS_SOURCE_BUNDLING_SOURCES = existsSync5(
-  resolve7(SOURCE_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
+  resolve8(SOURCE_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
 );
-var PACKAGED_REPO_ROOT = resolve7(SDK_PACKAGE_ROOT, "dist", "repo");
+var PACKAGED_REPO_ROOT = resolve8(SDK_PACKAGE_ROOT, "dist", "repo");
 var HAS_PACKAGED_BUNDLING_SOURCES = existsSync5(
-  resolve7(PACKAGED_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
+  resolve8(PACKAGED_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
 );
-var PROJECT_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? SOURCE_REPO_ROOT : HAS_PACKAGED_BUNDLING_SOURCES ? PACKAGED_REPO_ROOT : resolve7(SDK_PACKAGE_ROOT, "..");
-var SDK_SOURCE_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? resolve7(SOURCE_REPO_ROOT, "sdk", "src") : HAS_PACKAGED_BUNDLING_SOURCES ? resolve7(PACKAGED_REPO_ROOT, "sdk", "src") : resolve7(SDK_PACKAGE_ROOT, "src");
-var SDK_PACKAGE_JSON = resolve7(SDK_PACKAGE_ROOT, "package.json");
-var SDK_ENTRY_FILE = resolve7(SDK_SOURCE_ROOT, "index.ts");
-var SDK_TYPES_ENTRY_FILE = HAS_SOURCE_BUNDLING_SOURCES ? SDK_ENTRY_FILE : resolve7(SDK_PACKAGE_ROOT, "dist", "index.d.ts");
-var SDK_WORKERS_ENTRY_FILE = resolve7(SDK_SOURCE_ROOT, "worker-play-entry.ts");
-var WORKERS_HARNESS_ENTRY_FILE = resolve7(PROJECT_ROOT, "apps", "play-runner-workers", "src", "entry.ts");
-var WORKERS_HARNESS_FILES_DIR = resolve7(PROJECT_ROOT, "apps", "play-runner-workers", "src");
+var PROJECT_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? SOURCE_REPO_ROOT : HAS_PACKAGED_BUNDLING_SOURCES ? PACKAGED_REPO_ROOT : resolve8(SDK_PACKAGE_ROOT, "..");
+var SDK_SOURCE_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? resolve8(SOURCE_REPO_ROOT, "sdk", "src") : HAS_PACKAGED_BUNDLING_SOURCES ? resolve8(PACKAGED_REPO_ROOT, "sdk", "src") : resolve8(SDK_PACKAGE_ROOT, "src");
+var SDK_PACKAGE_JSON = resolve8(SDK_PACKAGE_ROOT, "package.json");
+var SDK_ENTRY_FILE = resolve8(SDK_SOURCE_ROOT, "index.ts");
+var SDK_TYPES_ENTRY_FILE = HAS_SOURCE_BUNDLING_SOURCES ? SDK_ENTRY_FILE : resolve8(SDK_PACKAGE_ROOT, "dist", "index.d.ts");
+var SDK_WORKERS_ENTRY_FILE = resolve8(SDK_SOURCE_ROOT, "worker-play-entry.ts");
+var WORKERS_HARNESS_ENTRY_FILE = resolve8(PROJECT_ROOT, "apps", "play-runner-workers", "src", "entry.ts");
+var WORKERS_HARNESS_FILES_DIR = resolve8(PROJECT_ROOT, "apps", "play-runner-workers", "src");
 var hasWarnedAboutNonDevelopmentBundling = false;
 function warnAboutNonDevelopmentBundling(filePath) {
   if (hasWarnedAboutNonDevelopmentBundling) {
@@ -5075,7 +5327,7 @@ function defaultPlayBundleTarget() {
 function createSdkPlayBundlingAdapter() {
   return {
     projectRoot: PROJECT_ROOT,
-    nodeModulesDir: resolve7(PROJECT_ROOT, "node_modules"),
+    nodeModulesDir: resolve8(PROJECT_ROOT, "node_modules"),
     cacheDir: join5(tmpdir2(), `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION2}`),
     sdkSourceRoot: SDK_SOURCE_ROOT,
     sdkPackageJson: SDK_PACKAGE_JSON,
@@ -5313,7 +5565,7 @@ function traceCliSync(phase, fields, run) {
   }
 }
 function sleep4(ms) {
-  return new Promise((resolve10) => setTimeout(resolve10, ms));
+  return new Promise((resolve11) => setTimeout(resolve11, ms));
 }
 function parseReferencedPlayTarget(target) {
   const trimmed = target.trim();
@@ -5359,7 +5611,7 @@ function formatPlayListReference(play) {
 function defaultMaterializedPlayPath(reference) {
   const playName = parseReferencedPlayTarget(reference).unqualifiedPlayName;
   const safeName = playName.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-  return resolve8(`${safeName || "play"}.play.ts`);
+  return resolve9(`${safeName || "play"}.play.ts`);
 }
 function materializeRemotePlaySource(input) {
   if (isFileTarget(input.target)) {
@@ -5370,14 +5622,14 @@ function materializeRemotePlaySource(input) {
   }
   const outputPath = input.outPath ?? defaultMaterializedPlayPath(input.playName);
   if (existsSync6(outputPath)) {
-    const existingSource = readFileSync4(outputPath, "utf-8");
+    const existingSource = readFileSync5(outputPath, "utf-8");
     if (existingSource === input.sourceCode) {
       return { path: outputPath, status: "unchanged", created: false };
     }
-    writeFileSync5(outputPath, input.sourceCode, "utf-8");
+    writeFileSync6(outputPath, input.sourceCode, "utf-8");
     return { path: outputPath, status: "updated", created: false };
   }
-  writeFileSync5(outputPath, input.sourceCode, "utf-8");
+  writeFileSync6(outputPath, input.sourceCode, "utf-8");
   return { path: outputPath, status: "created", created: true };
 }
 function formatLoadedPlayMessage(materializedFile) {
@@ -5422,7 +5674,7 @@ function extractPlayName(code, filePath) {
   throw buildMissingDefinePlayError(filePath);
 }
 function isFileTarget(target) {
-  return existsSync6(resolve8(target));
+  return existsSync6(resolve9(target));
 }
 function looksLikeFilePath(target) {
   if (target.trim().toLowerCase().startsWith("prebuilt/")) {
@@ -5441,7 +5693,7 @@ function parsePositiveInteger2(value, flagName) {
   return parsed;
 }
 function parseJsonInput(raw) {
-  const source = raw.startsWith("@") ? readFileSync4(resolve8(raw.slice(1)), "utf-8") : raw;
+  const source = raw.startsWith("@") ? readFileSync5(resolve9(raw.slice(1)), "utf-8") : raw;
   const parsed = JSON.parse(source);
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error("--input must be a JSON object.");
@@ -5542,7 +5794,7 @@ function fileInputBindingsFromStaticPipeline(staticPipeline) {
 function isLocalFilePathValue(value) {
   if (typeof value !== "string" || !value.trim()) return false;
   if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value.trim())) return false;
-  return existsSync6(resolve8(value));
+  return existsSync6(resolve9(value));
 }
 function inputContainsLocalFilePath(value) {
   if (isLocalFilePathValue(value)) {
@@ -5568,7 +5820,7 @@ async function stageFileInputArgs(input) {
   const localFiles = uniqueBindings.flatMap((binding) => {
     const value = getDottedInputValue(input.runtimeInput, binding.inputPath);
     if (!isLocalFilePathValue(value)) return [];
-    const absolutePath = resolve8(value);
+    const absolutePath = resolve9(value);
     return [{ binding, absolutePath, logicalPath: basename3(absolutePath) }];
   });
   if (localFiles.length === 0) {
@@ -5593,7 +5845,7 @@ async function stageFileInputArgs(input) {
   };
 }
 function stageFile(logicalPath, absolutePath) {
-  const buffer = readFileSync4(absolutePath);
+  const buffer = readFileSync5(absolutePath);
   return {
     logicalPath,
     contentBase64: buffer.toString("base64"),
@@ -5604,9 +5856,9 @@ function stageFile(logicalPath, absolutePath) {
 }
 function normalizePlayPath(filePath) {
   try {
-    return realpathSync.native(resolve8(filePath));
+    return realpathSync.native(resolve9(filePath));
   } catch {
-    return resolve8(filePath);
+    return resolve9(filePath);
   }
 }
 function formatBundlingErrors(filePath, errors) {
@@ -5759,11 +6011,42 @@ function isTransientPlayStreamError(error) {
     text
   );
 }
+function playStatusErrorText(status) {
+  const chunks = [];
+  const progressError = status.progress?.error;
+  if (typeof progressError === "string" && progressError.trim()) {
+    chunks.push(progressError.trim());
+  }
+  const errorValue = status.error;
+  if (typeof errorValue === "string" && errorValue.trim()) {
+    chunks.push(errorValue.trim());
+  }
+  const errors = status.errors;
+  if (Array.isArray(errors)) {
+    for (const error of errors) {
+      if (typeof error === "string" && error.trim()) {
+        chunks.push(error.trim());
+      } else if (error && typeof error === "object") {
+        const message = error.message;
+        if (typeof message === "string" && message.trim()) {
+          chunks.push(message.trim());
+        }
+      }
+    }
+  }
+  return chunks.join("; ") || status.status;
+}
+function isRetryablePendingStartFailure(status) {
+  if (status.status !== "failed") return false;
+  if (status.runId && status.runId !== "pending") return false;
+  return isTransientPlayStreamError(new Error(playStatusErrorText(status)));
+}
 var TERMINAL_PLAY_STATUSES2 = /* @__PURE__ */ new Set([
   "completed",
   "failed",
   "cancelled"
 ]);
+var PLAY_START_TRANSIENT_RETRY_DELAYS_MS = [500, 1500];
 function getEventPayload(event) {
   return event.payload && typeof event.payload === "object" ? event.payload : {};
 }
@@ -5830,10 +6113,6 @@ function openPlayDashboard(input) {
   }
   openInBrowser(input.dashboardUrl);
 }
-function getDashboardUrlFromLiveEvent(event) {
-  const dashboardUrl = getEventPayload(event).dashboardUrl;
-  return typeof dashboardUrl === "string" && dashboardUrl.trim() ? dashboardUrl.trim() : null;
-}
 function printPlayLogLines(input) {
   for (const line of input.lines) {
     if (input.emitLogs) {
@@ -5902,7 +6181,7 @@ async function waitForPlayCompletionByStream(input) {
           billing: false
         });
         if (TERMINAL_PLAY_STATUSES2.has(finalStatus.status)) {
-          return finalStatus;
+          return input.dashboardUrl ? { ...finalStatus, dashboardUrl: input.dashboardUrl } : finalStatus;
         }
       }
     }
@@ -5929,7 +6208,39 @@ async function waitForPlayCompletionByStream(input) {
   );
 }
 async function startAndWaitForPlayCompletionByStream(input) {
+  for (let attempt = 0; attempt <= PLAY_START_TRANSIENT_RETRY_DELAYS_MS.length; attempt += 1) {
+    const status = await startAndWaitForPlayCompletionByStreamOnce(input);
+    const retryDelayMs = PLAY_START_TRANSIENT_RETRY_DELAYS_MS[attempt];
+    if (retryDelayMs === void 0 || !isRetryablePendingStartFailure(status)) {
+      return status;
+    }
+    if (!input.jsonOutput) {
+      input.progress.writeLine(
+        `[play watch] start failed before run id with a transient error; retrying (${playStatusErrorText(status)})`
+      );
+    }
+    recordCliTrace({
+      phase: "cli.play_start_stream_retry",
+      ms: 0,
+      ok: true,
+      playName: input.playName,
+      attempt: attempt + 1,
+      reason: playStatusErrorText(status)
+    });
+    await sleep4(retryDelayMs);
+  }
+  throw new DeeplineError(
+    `Play ${input.playName} did not start after retrying transient start failures.`,
+    void 0,
+    "PLAY_START_RETRY_EXHAUSTED"
+  );
+}
+async function startAndWaitForPlayCompletionByStreamOnce(input) {
   const startedAt = Date.now();
+  const dashboardUrl = buildPlayDashboardUrl(
+    input.client.baseUrl,
+    input.playName
+  );
   const state = {
     lastLogIndex: 0,
     emittedRunnerStarted: false
@@ -5960,7 +6271,6 @@ async function startAndWaitForPlayCompletionByStream(input) {
       }
       const workflowId = lastKnownWorkflowId || "pending";
       if (workflowId !== "pending" && !emittedDashboardUrl) {
-        const dashboardUrl = getDashboardUrlFromLiveEvent(event) ?? buildPlayDashboardUrl(input.client.baseUrl, input.playName);
         openPlayDashboard({
           dashboardUrl,
           jsonOutput: input.jsonOutput,
@@ -6009,7 +6319,7 @@ async function startAndWaitForPlayCompletionByStream(input) {
           firstRunIdMs,
           lastPhase
         });
-        return finalStatus;
+        return { ...finalStatus, dashboardUrl };
       }
     }
   } catch (error) {
@@ -6046,6 +6356,7 @@ async function startAndWaitForPlayCompletionByStream(input) {
       return waitForPlayCompletionByStream({
         client: input.client,
         workflowId: lastKnownWorkflowId,
+        dashboardUrl,
         jsonOutput: input.jsonOutput,
         emitLogs: input.emitLogs,
         waitTimeoutMs: input.waitTimeoutMs,
@@ -6080,6 +6391,7 @@ async function startAndWaitForPlayCompletionByStream(input) {
     return waitForPlayCompletionByStream({
       client: input.client,
       workflowId: lastKnownWorkflowId,
+      dashboardUrl,
       jsonOutput: input.jsonOutput,
       emitLogs: input.emitLogs,
       waitTimeoutMs: input.waitTimeoutMs,
@@ -6250,12 +6562,25 @@ function buildRunWarnings(status, rowsInfo) {
   }
   return [];
 }
-function buildRunNextCommands(runId) {
-  return {
+function buildRunNextCommands(status) {
+  const runId = status.runId?.trim();
+  if (!runId) {
+    const playName = extractRunPlayName(status);
+    return playName ? {
+      list: `deepline runs list --play ${playName} --json`
+    } : {
+      list: "deepline runs list --json"
+    };
+  }
+  const commands = {
     get: `deepline runs get ${runId} --json`,
     stop: `deepline runs stop ${runId} --reason "stale lock" --json`,
     logs: `deepline runs logs ${runId} --out run.log --json`
   };
+  if (status.dashboardUrl) {
+    commands.open = `Open ${status.dashboardUrl} to see results.`;
+  }
+  return commands;
 }
 var RUN_LOG_PREVIEW_LIMIT = 20;
 function getRecordField(value, key) {
@@ -6276,6 +6601,121 @@ function getTimestampField(value, key) {
   }
   return typeof field === "string" && field.trim() ? field : null;
 }
+function getObjectField(value, key) {
+  const field = getRecordField(value, key);
+  return field && typeof field === "object" && !Array.isArray(field) ? field : null;
+}
+function formatCreditAmount(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return String(value ?? "-");
+  }
+  return Number(value.toFixed(8)).toString();
+}
+function extractJsonObjectFromText(text) {
+  const start = text.indexOf("{");
+  if (start < 0) {
+    return null;
+  }
+  const suffix = text.slice(start);
+  try {
+    const parsed = JSON.parse(suffix);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = start; index < text.length; index += 1) {
+      const char = text[index];
+      if (inString) {
+        if (escaped) {
+          escaped = false;
+        } else if (char === "\\") {
+          escaped = true;
+        } else if (char === '"') {
+          inString = false;
+        }
+        continue;
+      }
+      if (char === '"') {
+        inString = true;
+      } else if (char === "{") {
+        depth += 1;
+      } else if (char === "}") {
+        depth -= 1;
+        if (depth === 0) {
+          try {
+            const parsed = JSON.parse(text.slice(start, index + 1));
+            return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+          } catch {
+            return null;
+          }
+        }
+      }
+    }
+  }
+  return null;
+}
+function extractBillingFromText(text) {
+  if (!text) {
+    return null;
+  }
+  const parsed = extractJsonObjectFromText(text);
+  return getObjectField(parsed, "billing");
+}
+function extractToolIdFromErrorText(text) {
+  if (!text) {
+    return null;
+  }
+  const lowerToolMatch = /\btool\s+([A-Za-z0-9_.:-]+)\s+\d{3}\b/.exec(text);
+  if (lowerToolMatch?.[1]) {
+    return lowerToolMatch[1];
+  }
+  const upperToolMatch = /\bTool\s+([A-Za-z0-9_.:-]+)\s+failed\b/.exec(text);
+  return upperToolMatch?.[1] ?? null;
+}
+function isInsufficientCreditsBilling(billing) {
+  return billing?.kind === "insufficient_credits";
+}
+function extractBillingForStatus(status, error) {
+  const errorBilling = getObjectField(status, "errorBilling");
+  if (errorBilling) {
+    return errorBilling;
+  }
+  const directErrors = getRecordField(status, "errors");
+  if (Array.isArray(directErrors)) {
+    for (const entry of directErrors) {
+      const billing = getObjectField(entry, "billing");
+      if (billing) {
+        return billing;
+      }
+    }
+  }
+  const progressError = getStringField(status.progress, "error");
+  return extractBillingFromText(error) ?? extractBillingFromText(progressError) ?? getObjectField(status, "billing");
+}
+function formatInsufficientCreditsMessage(input) {
+  const operation = getStringField(input.billing, "operation_id") ?? getStringField(input.billing, "operation") ?? extractToolIdFromErrorText(input.error) ?? getStringField(input.billing, "provider") ?? "tool call";
+  const balance = formatCreditAmount(input.billing.balance_credits);
+  const required = formatCreditAmount(input.billing.required_credits);
+  const recommended = formatCreditAmount(
+    input.billing.recommended_add_credits ?? input.billing.needed_credits
+  );
+  const billingUrl = getStringField(input.billing, "billing_url");
+  const workspace = getStringField(input.billing, "workspace_id") ?? getStringField(input.billing, "workspaceId");
+  const workspaceSuffix = workspace ? ` (workspace=${workspace})` : "";
+  const addSuffix = billingUrl && recommended !== "-" ? ` Add >=${recommended} at ${billingUrl}.` : billingUrl ? ` Add credits at ${billingUrl}.` : "";
+  return `Workspace balance ${balance} < required ${required} for ${operation}${workspaceSuffix}.${addSuffix}`;
+}
+function formatPlayErrorForDisplay(status, error) {
+  if (!error) {
+    return null;
+  }
+  const billing = extractBillingForStatus(status, error);
+  if (isInsufficientCreditsBilling(billing)) {
+    return formatInsufficientCreditsMessage({ billing, error });
+  }
+  return error;
+}
 function normalizeRunStatusForEnvelope(status) {
   const run = status.run ?? null;
   return {
@@ -6326,18 +6766,33 @@ function normalizeErrorsForEnvelope(status, error) {
   if (Array.isArray(directErrors)) {
     return directErrors.filter(
       (entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)
-    );
+    ).map((entry) => {
+      const message2 = typeof entry.message === "string" && entry.message.trim() ? entry.message : error;
+      const billing2 = getObjectField(entry, "billing");
+      if (!isInsufficientCreditsBilling(billing2) || !message2) {
+        return entry;
+      }
+      return {
+        ...entry,
+        message: formatInsufficientCreditsMessage({ billing: billing2, error: message2 }),
+        billing: stripProviderSpendFromBilling(billing2)
+      };
+    });
   }
   if (!error) {
     return [];
   }
+  const nextCommands = buildRunNextCommands(status);
+  const billing = extractBillingForStatus(status, error);
+  const message = formatPlayErrorForDisplay(status, error) ?? error;
   return [
     {
       code: getStringField(status, "errorCode") ?? "RUN_FAILED",
       phase: getStringField(status, "errorPhase") ?? "runtime",
-      message: error,
+      message,
       retryable: typeof getRecordField(status, "retryable") === "boolean" ? getRecordField(status, "retryable") : null,
-      nextAction: `deepline runs get ${status.runId} --json`
+      ...billing ? { billing: stripProviderSpendFromBilling(billing) } : {},
+      nextAction: nextCommands.get ?? nextCommands.list
     }
   ];
 }
@@ -6386,24 +6841,26 @@ function compactPlayStatus(status) {
   ) : null;
   const progressError = status.progress?.error;
   const error = typeof progressError === "string" ? progressError : typeof status.error === "string" ? String(status.error) : null;
+  const displayError = formatPlayErrorForDisplay(status, error);
   return {
     runId: status.runId,
     apiVersion: status.apiVersion ?? 1,
     ...typeof status.name === "string" ? { name: status.name } : {},
     ...typeof status.playName === "string" ? { playName: status.playName } : {},
+    ...status.dashboardUrl ? { dashboardUrl: status.dashboardUrl } : {},
     status: status.status,
     run: normalizeRunStatusForEnvelope(status),
     progress: normalizeProgressForEnvelope(status, rowsInfo),
     steps: normalizeStepsForEnvelope(status),
     errors: normalizeErrorsForEnvelope(status, error),
     logs: normalizeLogsForEnvelope(status),
-    ...error ? { error } : {},
+    ...displayError ? { error: displayError } : {},
     ...warnings.length > 0 ? { warnings } : {},
     ...result !== void 0 ? { result } : {},
     ...status.resultView ? { resultView: status.resultView } : {},
     ...datasetStats ? { dataset_stats: datasetStats } : {},
     ...billing ? { billing } : {},
-    next: buildRunNextCommands(status.runId)
+    next: buildRunNextCommands(status)
   };
 }
 function enrichPlayStatusWithDatasetStats(status) {
@@ -6477,7 +6934,8 @@ function writePlayResult(status, jsonOutput, options) {
   lines.push(...formatDatasetStatsLines(datasetStats));
   const progressError = status.progress?.error;
   if (progressError && typeof progressError === "string") {
-    lines.push(`  error: ${progressError.slice(0, 200)}`);
+    const displayError = formatPlayErrorForDisplay(status, progressError) ?? progressError;
+    lines.push(`  error: ${displayError.slice(0, 200)}`);
   }
   const renderedServerView = renderServerResultView(status.resultView);
   if (result) {
@@ -6501,8 +6959,11 @@ var RUN_EXPORT_PAGE_SIZE = 5e3;
 function shellSingleQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+function sqlStringLiteral(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
 function runExportRetryCommand(runId, outPath, datasetPath) {
-  return `deepline runs export ${runId}${datasetPath ? ` --dataset ${shellSingleQuote(datasetPath)}` : ""} --out ${shellSingleQuote(resolve8(outPath))}`;
+  return `deepline runs export ${runId}${datasetPath ? ` --dataset ${shellSingleQuote(datasetPath)}` : ""} --out ${shellSingleQuote(resolve9(outPath))}`;
 }
 function extractRunPlayName(status) {
   const run = status.run;
@@ -6519,6 +6980,26 @@ function extractRunPlayName(status) {
   }
   return null;
 }
+function normalizeCustomerDbIdentifier(value) {
+  return value.split("/").pop().replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+}
+function buildCustomerDbQueryPlan(input) {
+  const playName = extractRunPlayName(input.status);
+  const tableNamespace = input.rowsInfo.tableNamespace?.trim();
+  if (!playName || !tableNamespace || input.rowsInfo.totalRows <= 0) {
+    return null;
+  }
+  const tableName = `${normalizeCustomerDbIdentifier(playName)}_${normalizeCustomerDbIdentifier(
+    tableNamespace
+  )}`;
+  const sql = `select * from "storage"."${tableName}" where _run_id = ${sqlStringLiteral(input.status.runId)} limit ${input.rowsInfo.totalRows}`;
+  const base = `deepline customer-db query --sql ${shellSingleQuote(sql)} --max-rows ${input.rowsInfo.totalRows}`;
+  return {
+    sql,
+    json: `${base} --json`,
+    csv: `${base} --format csv --out ${shellSingleQuote(resolve9(input.outPath))}`
+  };
+}
 function exportableSheetRow(row) {
   if (!row || typeof row !== "object" || Array.isArray(row)) {
     return null;
@@ -6616,7 +7097,7 @@ async function exportPlayStatusRows(client, status, outPath, options = {}) {
     return null;
   }
   const availableRows = collectSerializedDatasetRowsInfos(status);
-  let rowsInfo = options.datasetPath ? availableRows.find((info) => info.source === options.datasetPath) ?? null : availableRows.length === 1 ? availableRows[0] : null;
+  const rowsInfo = options.datasetPath ? availableRows.find((info) => info.source === options.datasetPath) ?? null : availableRows.length === 1 ? availableRows[0] : null;
   if (!rowsInfo && options.datasetPath) {
     const available = availableRows.map((info) => info.source).filter((source) => typeof source === "string");
     throw new DeeplineError(
@@ -6690,6 +7171,60 @@ async function exportPlayStatusRows(client, status, outPath, options = {}) {
   }
   return { path: writeCanonicalRowsCsv(rowsInfo, outPath), rowsInfo };
 }
+function extractActiveRunsFromError(error) {
+  if (!(error instanceof DeeplineError)) {
+    return [];
+  }
+  const response = error.details?.response;
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    return [];
+  }
+  const details = response.details;
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    return [];
+  }
+  const activeRuns = details.activeRuns;
+  return Array.isArray(activeRuns) ? activeRuns.filter(
+    (run) => Boolean(run) && typeof run === "object" && !Array.isArray(run)
+  ) : [];
+}
+function activeRunId(run) {
+  return getStringField(run, "workflowId") ?? getStringField(run, "runId");
+}
+function formatActiveRunConflictError(input) {
+  const lines = [
+    `Active run exists for ${input.playName}. Use --force to supersede, or inspect/stop the active run first.`
+  ];
+  for (const run of input.activeRuns.slice(0, 3)) {
+    const runId = activeRunId(run);
+    if (!runId) {
+      continue;
+    }
+    const status = getStringField(run, "status");
+    const startedAt = getStringField(run, "startedAt") ?? getStringField(run, "startTime");
+    lines.push(
+      `  active: ${runId}${status ? ` status=${status}` : ""}${startedAt ? ` startedAt=${startedAt}` : ""}`
+    );
+    lines.push(`  get: deepline runs get ${runId} --json`);
+    lines.push(
+      `  stop: deepline runs stop ${runId} --reason "stale lock" --json`
+    );
+  }
+  lines.push(`  rerun: add --force to the same deepline plays run command`);
+  return lines.join("\n");
+}
+function normalizePlayStartError(error, playName) {
+  const activeRuns = extractActiveRunsFromError(error);
+  if (activeRuns.length === 0) {
+    return error;
+  }
+  return new DeeplineError(
+    formatActiveRunConflictError({ playName, activeRuns }),
+    error instanceof DeeplineError ? error.statusCode : 409,
+    "ACTIVE_RUN_EXISTS",
+    error instanceof DeeplineError ? error.details : void 0
+  );
+}
 function renderServerResultView(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return { lines: [], actions: [] };
@@ -6925,12 +7460,12 @@ function shouldUseLocalOnlyPlayCheck() {
 async function handlePlayCheck(args) {
   const options = parsePlayCheckOptions(args);
   if (!isFileTarget(options.target)) {
-    const resolved = resolve8(options.target);
+    const resolved = resolve9(options.target);
     console.error(`File not found: ${resolved}`);
     return 1;
   }
-  const absolutePlayPath = resolve8(options.target);
-  const sourceCode = readFileSync4(absolutePlayPath, "utf-8");
+  const absolutePlayPath = resolve9(options.target);
+  const sourceCode = readFileSync5(absolutePlayPath, "utf-8");
   let graph;
   try {
     graph = await collectBundledPlayGraph(absolutePlayPath);
@@ -6993,12 +7528,12 @@ async function handleFileBackedRun(options) {
   }
   const client = new DeeplineClient();
   const progress = getActiveCliProgress() ?? createCliProgress(!options.jsonOutput);
-  const absolutePlayPath = resolve8(options.target.path);
+  const absolutePlayPath = resolve9(options.target.path);
   progress.phase("compiling play");
   const sourceCode = traceCliSync(
     "cli.play_file_read_source",
     { targetKind: "file" },
-    () => readFileSync4(absolutePlayPath, "utf-8")
+    () => readFileSync5(absolutePlayPath, "utf-8")
   );
   const runtimeInput = options.input ? { ...options.input } : {};
   let graph;
@@ -7079,6 +7614,8 @@ async function handleFileBackedRun(options) {
         waitTimeoutMs: options.waitTimeoutMs,
         noOpen: options.noOpen,
         progress
+      }).catch((error) => {
+        throw normalizePlayStartError(error, playName);
       })
     );
     if (finalStatus.status === "completed") {
@@ -7097,10 +7634,11 @@ async function handleFileBackedRun(options) {
   const started = await traceCliSpan(
     "cli.play_start_unwatched",
     { targetKind: "file", playName },
-    () => client.startPlayRun(startRequest)
+    () => client.startPlayRun(startRequest).catch((error) => {
+      throw normalizePlayStartError(error, playName);
+    })
   );
-  const dashboardUrl = buildPlayDashboardUrl(client.baseUrl, playName);
-  const resolvedDashboardUrl = started.dashboardUrl ?? dashboardUrl;
+  const resolvedDashboardUrl = buildPlayDashboardUrl(client.baseUrl, playName);
   openPlayDashboard({
     dashboardUrl: resolvedDashboardUrl,
     jsonOutput: options.jsonOutput,
@@ -7215,6 +7753,8 @@ async function handleNamedRun(options) {
         waitTimeoutMs: options.waitTimeoutMs,
         noOpen: options.noOpen,
         progress
+      }).catch((error) => {
+        throw normalizePlayStartError(error, playName);
       })
     );
     if (finalStatus.status === "completed") {
@@ -7233,13 +7773,11 @@ async function handleNamedRun(options) {
   const started = await traceCliSpan(
     "cli.play_start_unwatched",
     { targetKind: "name", playName },
-    () => client.startPlayRun(startRequest)
-  );
-  const dashboardUrl = buildPlayDashboardUrl(
-    client.baseUrl,
-    playName
+    () => client.startPlayRun(startRequest).catch((error) => {
+      throw normalizePlayStartError(error, playName);
+    })
   );
-  const resolvedDashboardUrl = started.dashboardUrl ?? dashboardUrl;
+  const resolvedDashboardUrl = buildPlayDashboardUrl(client.baseUrl, playName);
   openPlayDashboard({
     dashboardUrl: resolvedDashboardUrl,
     jsonOutput: options.jsonOutput,
@@ -7263,7 +7801,7 @@ async function handlePlayRun(args) {
     if (isFileTarget(options.target.path)) {
       return handleFileBackedRun(options);
     }
-    const resolved = resolve8(options.target.path);
+    const resolved = resolve9(options.target.path);
     console.error(`File not found: ${resolved}`);
     const dir = dirname8(resolved);
     if (existsSync6(dir)) {
@@ -7410,14 +7948,14 @@ async function handleRunLogs(args) {
       continue;
     }
     if (arg === "--out" && args[index + 1]) {
-      outPath = resolve8(args[++index]);
+      outPath = resolve9(args[++index]);
     }
   }
   const client = new DeeplineClient();
   const status = await client.runs.get(runId);
   const logs = status.progress?.logs ?? [];
   if (outPath) {
-    writeFileSync5(outPath, `${logs.join("\n")}${logs.length > 0 ? "\n" : ""}`);
+    writeFileSync6(outPath, `${logs.join("\n")}${logs.length > 0 ? "\n" : ""}`);
     printCommandEnvelope({
       runId: status.runId,
       log_path: outPath,
@@ -7473,7 +8011,7 @@ async function handleRunStop(args) {
   return 0;
 }
 async function handleRunExport(args) {
-  const usage = "Usage: deepline runs export <run-id> [--dataset result.rows] --out output.csv [--json]";
+  const usage = "Usage: deepline runs export <run-id> [--dataset result.rows] --out output.csv [--metadata-out export.json] [--json]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage);
@@ -7483,14 +8021,19 @@ async function handleRunExport(args) {
   }
   let outPath = null;
   let datasetPath = null;
+  let metadataOutPath = null;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--out" && args[index + 1]) {
-      outPath = resolve8(args[++index]);
+      outPath = resolve9(args[++index]);
       continue;
     }
     if (arg === "--dataset" && args[index + 1]) {
       datasetPath = args[++index];
+      continue;
+    }
+    if (arg === "--metadata-out" && args[index + 1]) {
+      metadataOutPath = resolve9(args[++index]);
     }
   }
   if (!outPath) {
@@ -7502,15 +8045,59 @@ async function handleRunExport(args) {
   const exportResult = await exportPlayStatusRows(client, status, outPath, {
     datasetPath
   });
-  printCommandEnvelope({
+  const source = exportResult?.rowsInfo.source ?? datasetPath ?? null;
+  const queryPlan = exportResult && outPath ? buildCustomerDbQueryPlan({
+    status,
+    rowsInfo: exportResult.rowsInfo,
+    outPath
+  }) : null;
+  const next = {
+    ...buildRunNextCommands(status),
+    export: runExportRetryCommand(status.runId, outPath, datasetPath ?? source),
+    ...queryPlan ? {
+      queryJson: queryPlan.json,
+      queryCsv: queryPlan.csv
+    } : {}
+  };
+  const payload = {
     runId: status.runId,
     ...datasetPath ? { dataset: datasetPath } : {},
     csv_path: exportResult?.path ?? null,
+    source,
     rowCount: exportResult?.rowsInfo.totalRows ?? null,
     columns: exportResult?.rowsInfo.columns ?? [],
+    ...queryPlan ? {
+      query: {
+        sql: queryPlan.sql,
+        json: queryPlan.json,
+        csv: queryPlan.csv
+      }
+    } : {},
+    ...metadataOutPath ? { metadata_path: metadataOutPath } : {},
     local: { csv_path: exportResult?.path ?? null },
-    render: { sections: [{ title: "run export", lines: [`Exported ${status.runId} to ${exportResult?.path ?? outPath}`] }] }
-  }, { json: argsWantJson(args) });
+    next,
+    render: {
+      sections: [
+        {
+          title: "run export",
+          lines: [
+            `Exported ${status.runId} to ${exportResult?.path ?? outPath}`,
+            ...source ? [`source=${source}`] : [],
+            ...queryPlan ? [`query=${queryPlan.json}`] : []
+          ]
+        }
+      ]
+    }
+  };
+  if (metadataOutPath) {
+    writeFileSync6(
+      metadataOutPath,
+      `${JSON.stringify(payload, null, 2)}
+`,
+      "utf-8"
+    );
+  }
+  printCommandEnvelope(payload, { json: argsWantJson(args) });
   return 0;
 }
 async function handlePlayGet(args) {
@@ -7527,10 +8114,10 @@ async function handlePlayGet(args) {
   for (let index = 1; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--out" && args[index + 1]) {
-      outPath = resolve8(args[++index]);
+      outPath = resolve9(args[++index]);
     }
   }
-  const playName = isFileTarget(target) ? extractPlayName(readFileSync4(resolve8(target), "utf-8"), resolve8(target)) : parseReferencedPlayTarget(target).playName;
+  const playName = isFileTarget(target) ? extractPlayName(readFileSync5(resolve9(target), "utf-8"), resolve9(target)) : parseReferencedPlayTarget(target).playName;
   const detail = isFileTarget(target) ? await client.getPlay(playName) : await assertCanonicalNamedPlayReference(client, target);
   const resolvedSource = detail.play.workingRevision?.sourceCode ?? detail.play.liveRevision?.sourceCode ?? detail.play.currentRevision?.sourceCode ?? detail.play.sourceCode ?? "";
   const materializedFile = outPath ? materializeRemotePlaySource({
@@ -7822,7 +8409,7 @@ async function handlePlayPublish(args) {
     }
     let graph;
     try {
-      graph = await collectBundledPlayGraph(resolve8(playName));
+      graph = await collectBundledPlayGraph(resolve9(playName));
       await compileBundledPlayGraphManifests(client, graph);
       await publishImportedPlayDependencies(client, graph);
     } catch (error) {
@@ -8308,30 +8895,34 @@ Examples:
 Notes:
   Writes a returned dataset handle to the requested local CSV path. Use runs get
   first to inspect dataset paths like result.rows or result.nested.contacts.
+  --metadata-out writes the same export metadata object returned by --json,
+  including source and follow-on customer-db query commands when available.
 
 Examples:
   deepline runs export play/my-play/run/20260501t000000-000 --out output.csv
   deepline runs export play/my-play/run/20260501t000000-000 --dataset result.rows --out output.csv
+  deepline runs export play/my-play/run/20260501t000000-000 --out output.csv --metadata-out output.meta.json
   deepline runs export play/my-play/run/20260501t000000-000 --out output.csv --json
 `
-  ).requiredOption("--out <path>", "Output CSV path").option("--dataset <path>", "Returned dataset handle path, such as result.rows").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
+  ).requiredOption("--out <path>", "Output CSV path").option("--dataset <path>", "Returned dataset handle path, such as result.rows").option("--metadata-out <path>", "Write export metadata JSON to a file").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunExport([
       runId,
       ...options.dataset ? ["--dataset", options.dataset] : [],
       "--out",
       options.out,
+      ...options.metadataOut ? ["--metadata-out", options.metadataOut] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
 }
 
 // src/cli/commands/tools.ts
-import { chmodSync, mkdtempSync, writeFileSync as writeFileSync7 } from "fs";
+import { chmodSync, mkdtempSync, writeFileSync as writeFileSync8 } from "fs";
 import { tmpdir as tmpdir3 } from "os";
 import { join as join8 } from "path";
 
 // src/tool-output.ts
-import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync6 } from "fs";
+import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync7 } from "fs";
 import { homedir as homedir3 } from "os";
 import { join as join7 } from "path";
 function isPlainObject(value) {
@@ -8356,6 +8947,25 @@ function normalizeRows(value) {
 }
 function candidateRoots(payload) {
   const roots = [{ path: null, value: payload }];
+  if (isPlainObject(payload) && isPlainObject(payload.toolExecutionResult)) {
+    roots.push({ path: "toolExecutionResult", value: payload.toolExecutionResult });
+    const toolOutput = payload.toolExecutionResult.toolOutput;
+    if (isPlainObject(toolOutput)) {
+      roots.push({ path: "toolExecutionResult.toolOutput", value: toolOutput });
+      if (Object.prototype.hasOwnProperty.call(toolOutput, "raw")) {
+        roots.push({
+          path: "toolExecutionResult.toolOutput.raw",
+          value: toolOutput.raw
+        });
+      }
+    }
+  }
+  if (isPlainObject(payload) && isPlainObject(payload.output)) {
+    roots.push({ path: "output", value: payload.output });
+    if (Object.prototype.hasOwnProperty.call(payload.output, "body")) {
+      roots.push({ path: "output.body", value: payload.output.body });
+    }
+  }
   if (isPlainObject(payload) && isPlainObject(payload.result)) {
     roots.push({ path: "result", value: payload.result });
     if (isPlainObject(payload.result.data)) {
@@ -8415,7 +9025,7 @@ function ensureOutputDir() {
 function writeJsonOutputFile(payload, stem) {
   const outputDir = ensureOutputDir();
   const outputPath = join7(outputDir, `${stem}_${Date.now()}.json`);
-  writeFileSync6(outputPath, JSON.stringify(payload, null, 2), "utf-8");
+  writeFileSync7(outputPath, JSON.stringify(payload, null, 2), "utf-8");
   return outputPath;
 }
 function writeCsvOutputFile(rows, stem) {
@@ -8443,7 +9053,7 @@ function writeCsvOutputFile(rows, stem) {
   for (const row of rows) {
     lines.push(columns.map((column) => escapeCell(row[column])).join(","));
   }
-  writeFileSync6(outputPath, `${lines.join("\n")}
+  writeFileSync7(outputPath, `${lines.join("\n")}
 `, "utf-8");
   const previewRows = rows.slice(0, 5);
   const previewColumns = columns.slice(0, 5);
@@ -8489,8 +9099,7 @@ async function listTools(args) {
         title: `${items.length} tools available:`,
         lines: items.flatMap((item) => {
           const cats = item.categories.length ? ` [${item.categories.join(", ")}]` : "";
-          const listHint = item.listExtractorPaths?.length ? ` listExtractorPaths=${item.listExtractorPaths.join(",")}` : "";
-          return [`${item.toolId}${cats}`, `  ${item.description}${listHint}`];
+          return [`${item.toolId}${cats}`, `  ${item.description}`];
         })
       }
     ]
@@ -8569,7 +9178,7 @@ Common commands:
   deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
 
 Output:
-  Use describe for tool contracts. get is accepted as a compatibility alias.
+  Use describe for tool contracts.
   Use execute to run a tool. run is accepted as a compatibility alias.
 `
   );
@@ -8616,8 +9225,8 @@ Examples:
     `
 Notes:
   Shows the tool contract, input schema, output schema, Deepline cost, aliases,
-  and metadata. describe is the preferred discovery verb. get is kept as a
-  compatibility alias for the same metadata surface.
+  and metadata. describe is the supported discovery verb. get is removed in
+  the V2 SDK CLI; use describe for the same metadata surface.
 
 Examples:
   deepline tools describe hunter_email_verifier
@@ -8630,7 +9239,22 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  addToolMetadataCommand(tools.command("describe <toolId>").alias("get"));
+  addToolMetadataCommand(tools.command("describe <toolId>"));
+  tools.command("get <toolId>").description("Deprecated. Use tools describe.").addHelpText(
+    "after",
+    `
+Examples:
+  deepline tools describe hunter_email_verifier --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (toolId, options) => {
+    const message = `tools get has been removed from the V2 SDK CLI. Use: deepline tools describe ${toolId} --json`;
+    if (options.json || shouldEmitJson()) {
+      printJsonError({ message, code: "TOOLS_GET_REMOVED" });
+    } else {
+      console.error(message);
+    }
+    process.exitCode = 2;
+  });
   tools.command("execute <toolId>").alias("run").description("Execute a tool by id.").addHelpText(
     "after",
     `
@@ -8711,6 +9335,7 @@ function printToolDetails(tool, requestedToolId) {
   const stepContributions = arrayField(tool, "stepContributions", "step_contributions");
   const playExpansion = recordField(tool, "playExpansion", "play_expansion");
   const samples = recordField(tool, "samples");
+  const usageGuidance = recordField(tool, "usageGuidance", "usage_guidance");
   console.log(`Tool: ${toolId}`);
   if (displayName) {
     console.log("  Display name:");
@@ -8774,14 +9399,16 @@ function printToolDetails(tool, requestedToolId) {
     console.log("  Tip: pass --payload with a JSON object.");
   }
   printSamples(samples);
+  printUsageGuidance(usageGuidance);
   if (isPlayTool(tool)) {
     console.log("  Play contract:");
     console.log("    - This is a deepline-native waterfall; the returned rows are extracted by target getters, not by hand-authored payload shape.");
     if (playExpansion && typeof playExpansion.group === "string" && playExpansion.group.trim()) {
       console.log(`    - Output alias/runtime group is: ${playExpansion.group.trim()}`);
     }
-    const getters = recordField(tool, "resultIdentityGetters", "result_identity_getters");
-    const targets = Object.keys(getters).filter(Boolean).sort();
+    const toolExecutionResult = recordField(usageGuidance, "toolExecutionResult");
+    const extractedValues = arrayField(toolExecutionResult, "extractedValues", "extracted_values");
+    const targets = extractedValues.map((entry) => isRecord3(entry) && typeof entry.name === "string" ? entry.name : "").filter(Boolean).sort();
     if (targets.length) {
       console.log(`    - Built-in extract targets: ${targets.join(", ")}`);
     }
@@ -8800,7 +9427,53 @@ function printToolDetails(tool, requestedToolId) {
   } else {
     console.log(`  deepline tools execute ${toolId} --payload '{...}'`);
   }
-  console.log("  deepline tools get <tool_id> --json  # full machine-readable output");
+  console.log("  deepline tools describe <tool_id> --json");
+}
+function printUsageGuidance(usageGuidance) {
+  if (Object.keys(usageGuidance).length === 0) return;
+  const execute = stringField(usageGuidance, "execute");
+  const toolExecutionResult = recordField(usageGuidance, "toolExecutionResult", "tool_execution_result");
+  const toolOutput = recordField(toolExecutionResult, "toolOutput", "tool_output");
+  const extractedLists = extractionEntries(toolExecutionResult, "extractedLists", "extracted_lists");
+  const extractedValues = extractionEntries(toolExecutionResult, "extractedValues", "extracted_values");
+  console.log("  Usage guidance:");
+  if (execute) console.log(`    ${execute}`);
+  const raw = pathField(toolOutput, "raw");
+  const meta = pathField(toolOutput, "meta");
+  if (raw) console.log(`    Raw tool output: ${raw}`);
+  if (meta) console.log(`    Tool output metadata: ${meta}`);
+  printExtractions("Extracted lists", extractedLists);
+  printExtractions("Extracted values", extractedValues);
+}
+function pathField(record, key) {
+  const value = record[key];
+  if (typeof value === "string") return value.trim();
+  if (isRecord3(value)) return stringField(value, "path");
+  return "";
+}
+function extractionEntries(record, camelKey, snakeKey) {
+  const value = record[camelKey] ?? record[snakeKey];
+  if (Array.isArray(value)) return value;
+  if (!isRecord3(value)) return [];
+  return Object.entries(value).map(
+    ([name, entry]) => isRecord3(entry) ? { name, ...entry } : { name }
+  );
+}
+function printExtractions(label, entries) {
+  if (!entries.length) return;
+  console.log(`    ${label}:`);
+  for (const entry of entries) {
+    if (!isRecord3(entry)) continue;
+    const name = stringField(entry, "name");
+    const expression = stringField(entry, "expression");
+    const details = recordField(entry, "details");
+    const rawToolOutputPaths = arrayField(details, "rawToolOutputPaths", "raw_tool_output_paths").map((value) => typeof value === "string" ? value.trim() : "").filter(Boolean);
+    const candidatePaths = arrayField(details, "candidatePaths", "candidate_paths").map((value) => typeof value === "string" ? value.trim() : "").filter(Boolean);
+    if (!name || !expression) continue;
+    const paths = candidatePaths.length ? candidatePaths : rawToolOutputPaths;
+    const pathSuffix = paths.length ? ` from ${paths.join(", ")}` : "";
+    console.log(`      - ${name}: ${expression}${pathSuffix}`);
+  }
 }
 function printToolCost(input) {
   const { cost, billingSource, deeplineCredits, deeplineUsdPerPricingUnit } = input;
@@ -8868,6 +9541,17 @@ function samplePayload(samples, key) {
 function commandEnvelopeFromRawResponse(rawResponse) {
   return isRecord3(rawResponse) ? { ...rawResponse } : { status: "completed", result: rawResponse };
 }
+function listExtractorPathsFromUsageGuidance(tool) {
+  const toolExecutionResult = tool.usageGuidance?.toolExecutionResult;
+  const extractedLists = Array.isArray(toolExecutionResult?.extractedLists) ? toolExecutionResult.extractedLists : isRecord3(toolExecutionResult?.extractedLists) ? Object.values(toolExecutionResult.extractedLists) : [];
+  return extractedLists.flatMap((entry) => {
+    const paths = entry.details?.candidatePaths ?? entry.details?.rawToolOutputPaths;
+    if (!Array.isArray(paths)) return [];
+    return paths.map(
+      (path) => path.trim().replace(/^toolExecutionResult\.toolOutput\.raw\.?/, "").replace(/^\./, "")
+    ).filter(Boolean);
+  });
+}
 function isPlayTool(tool) {
   const provider = typeof tool.provider === "string" ? tool.provider : "";
   return provider === "deepline_native" && Boolean(recordField(tool, "playExpansion", "play_expansion"));
@@ -8941,6 +9625,7 @@ function parseExecuteOptions(args) {
   const params = {};
   let outputFormat = "auto";
   let noPreview = false;
+  let fullOutput = false;
   for (let index = 1; index < args.length; index += 1) {
     const arg = args[index];
     if ((arg === "--param" || arg === "-p") && args[index + 1]) {
@@ -8967,6 +9652,7 @@ function parseExecuteOptions(args) {
     }
     if (arg === "--full-output") {
       outputFormat = "json";
+      fullOutput = true;
       continue;
     }
     if (arg === "--no-preview") {
@@ -8975,7 +9661,7 @@ function parseExecuteOptions(args) {
     }
     throw new Error(`Unknown option: ${arg}`);
   }
-  return { toolId, params, outputFormat, noPreview };
+  return { toolId, params, outputFormat, noPreview, fullOutput };
 }
 function safeFileStem(value) {
   return value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "tool";
@@ -9007,7 +9693,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
     description: ${JSON.stringify(`Seed ${input.toolId} rows for workflow expansion.`)},
   });
 
-  const list = Object.values(result.lists)[0];
+  const list = Object.values(result.extractedLists)[0];
   const rows = (list?.get() ?? []).slice(0, 100);
   // ${sampleRows}
   // columns: ${columns}
@@ -9024,7 +9710,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   };
 });
 `;
-  writeFileSync7(scriptPath, script, { encoding: "utf-8", mode: 384 });
+  writeFileSync8(scriptPath, script, { encoding: "utf-8", mode: 384 });
   return {
     path: scriptPath,
     projectDir,
@@ -9035,7 +9721,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
 function buildToolExecuteBaseEnvelope(input) {
   const envelope = commandEnvelopeFromRawResponse(input.rawResponse);
   const summaryEntries = Object.entries(input.summary);
-  const output = input.listConversion ? {
+  const outputPreview = input.listConversion ? {
     kind: "list",
     rowCount: input.listConversion.rows.length,
     columns: Object.keys(input.listConversion.rows[0] ?? {}),
@@ -9046,6 +9732,7 @@ function buildToolExecuteBaseEnvelope(input) {
     kind: summaryEntries.length > 0 ? "object" : "raw",
     summary: input.summary
   };
+  const envelopeHasCanonicalOutput = isRecord3(envelope.toolExecutionResult) && isRecord3(envelope.toolExecutionResult.toolOutput) && Object.prototype.hasOwnProperty.call(envelope.toolExecutionResult.toolOutput, "raw");
   const actions = input.listConversion ? [
     {
       label: "next",
@@ -9054,7 +9741,7 @@ function buildToolExecuteBaseEnvelope(input) {
   ] : [];
   return {
     ...envelope,
-    output,
+    ...envelopeHasCanonicalOutput ? { output_preview: outputPreview } : { output: outputPreview },
     ...summaryEntries.length > 0 ? { summary: input.summary } : {},
     next: input.listConversion ? {
       expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again."
@@ -9107,8 +9794,12 @@ async function executeTool(args) {
     throw error;
   }
   const rawResponse = await client.executeTool(parsed.toolId, parsed.params);
+  if (parsed.fullOutput) {
+    printJson(rawResponse);
+    return 0;
+  }
   const listConversion = tryConvertToList(rawResponse, {
-    listExtractorPaths: metadata.listExtractorPaths ?? []
+    listExtractorPaths: listExtractorPathsFromUsageGuidance(metadata)
   });
   const summary = extractSummaryFields(rawResponse);
   const baseEnvelope = buildToolExecuteBaseEnvelope({
@@ -9240,7 +9931,7 @@ async function executeTool(args) {
 // src/cli/commands/update.ts
 import { spawn } from "child_process";
 import { existsSync as existsSync7 } from "fs";
-import { dirname as dirname9, join as join9, resolve as resolve9 } from "path";
+import { dirname as dirname9, join as join9, resolve as resolve10 } from "path";
 function posixShellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -9259,7 +9950,7 @@ function buildSourceUpdateCommand(sourceRoot) {
   return `${cdCommand} && git fetch origin main --tags && git merge --ff-only origin/main`;
 }
 function findRepoBackedSdkRoot(startPath) {
-  let current = resolve9(startPath);
+  let current = resolve10(startPath);
   while (true) {
     if (existsSync7(join9(current, "sdk", "package.json")) && existsSync7(join9(current, "sdk", "bin", "deepline-dev.ts"))) {
       return current;
@@ -9270,7 +9961,7 @@ function findRepoBackedSdkRoot(startPath) {
   }
 }
 function resolveUpdatePlan() {
-  const entrypoint = process.argv[1] ? resolve9(process.argv[1]) : "";
+  const entrypoint = process.argv[1] ? resolve10(process.argv[1]) : "";
   const sourceRoot = entrypoint ? findRepoBackedSdkRoot(dirname9(entrypoint)) : null;
   if (sourceRoot) {
     return {
@@ -9363,8 +10054,8 @@ Examples:
 }
 
 // src/cli/skills-sync.ts
-import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync8, mkdirSync as mkdirSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync8 } from "fs";
+import { spawn as spawn2, spawnSync } from "child_process";
+import { existsSync as existsSync8, mkdirSync as mkdirSync5, readdirSync as readdirSync2, readFileSync as readFileSync6, statSync, writeFileSync as writeFileSync9 } from "fs";
 import { homedir as homedir4 } from "os";
 import { dirname as dirname10, join as join10 } from "path";
 var CHECK_TIMEOUT_MS2 = 3e3;
@@ -9383,7 +10074,7 @@ function readLocalSkillsVersion(baseUrl) {
   const path = sdkSkillsVersionPath(baseUrl);
   if (!existsSync8(path)) return "";
   try {
-    return readFileSync5(path, "utf-8").trim();
+    return readFileSync6(path, "utf-8").trim();
   } catch {
     return "";
   }
@@ -9391,9 +10082,45 @@ function readLocalSkillsVersion(baseUrl) {
 function writeLocalSkillsVersion(baseUrl, version) {
   const path = sdkSkillsVersionPath(baseUrl);
   mkdirSync5(dirname10(path), { recursive: true });
-  writeFileSync8(path, `${version}
+  writeFileSync9(path, `${version}
 `, "utf-8");
 }
+function installedSdkSkillHasStalePositionalExecuteExamples() {
+  const home = process.env.HOME?.trim() || homedir4();
+  const roots = [
+    join10(home, ".claude", "skills", SDK_SKILL_NAME),
+    join10(home, ".agents", "skills", SDK_SKILL_NAME)
+  ];
+  const staleMarkers = [
+    "ctx.tools.execute(key",
+    "ctx.tools.execute('",
+    'ctx.tools.execute("',
+    "rowCtx.tools.execute('",
+    'rowCtx.tools.execute("'
+  ];
+  const scan = (dir) => {
+    for (const entry of readdirSync2(dir)) {
+      const path = join10(dir, entry);
+      const stat3 = statSync(path);
+      if (stat3.isDirectory()) {
+        if (scan(path)) return true;
+        continue;
+      }
+      if (!entry.endsWith(".md")) continue;
+      const text = readFileSync6(path, "utf-8");
+      if (staleMarkers.some((marker) => text.includes(marker))) return true;
+    }
+    return false;
+  };
+  for (const root of roots) {
+    try {
+      if (existsSync8(root) && scan(root)) return true;
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}
 async function fetchSkillsUpdate(baseUrl, localVersion) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS2);
@@ -9429,7 +10156,7 @@ function buildSkillsInstallArgs(baseUrl) {
     "skills",
     "add",
     packageUrl,
-    "--agents",
+    "--agent",
     ...SKILL_AGENTS,
     "--global",
     "--yes",
@@ -9445,7 +10172,7 @@ function buildBunxSkillsInstallArgs(baseUrl) {
     "skills",
     "add",
     packageUrl,
-    "--agents",
+    "--agent",
     ...SKILL_AGENTS,
     "--global",
     "--yes",
@@ -9455,7 +10182,7 @@ function buildBunxSkillsInstallArgs(baseUrl) {
   ];
 }
 function hasCommand(command) {
-  const result = spawnSync2(command, ["--version"], {
+  const result = spawnSync(command, ["--version"], {
     stdio: "ignore",
     shell: process.platform === "win32"
   });
@@ -9485,7 +10212,7 @@ function resolveSkillsInstallCommands(baseUrl) {
   return [npxInstall];
 }
 function runOneSkillsInstall(install) {
-  return new Promise((resolve10) => {
+  return new Promise((resolve11) => {
     const child = spawn2(install.command, install.args, {
       stdio: ["ignore", "ignore", "pipe"],
       env: process.env
@@ -9495,7 +10222,7 @@ function runOneSkillsInstall(install) {
       stderr += chunk.toString("utf-8");
     });
     child.on("error", (error) => {
-      resolve10({
+      resolve11({
         ok: false,
         detail: `failed to start ${install.command}: ${error.message}`,
         manualCommand: install.manualCommand
@@ -9503,11 +10230,11 @@ function runOneSkillsInstall(install) {
     });
     child.on("close", (code) => {
       if (code === 0) {
-        resolve10({ ok: true, detail: "", manualCommand: install.manualCommand });
+        resolve11({ ok: true, detail: "", manualCommand: install.manualCommand });
         return;
       }
       const detail = stderr.trim();
-      resolve10({
+      resolve11({
         ok: false,
         detail: detail ? `${install.command}: ${detail}` : `${install.command} exited ${code}`,
         manualCommand: install.manualCommand
@@ -9546,10 +10273,19 @@ async function syncSdkSkillsIfNeeded(baseUrl) {
   attemptedSync = true;
   const localVersion = readLocalSkillsVersion(baseUrl);
   const update = await fetchSkillsUpdate(baseUrl, localVersion);
-  if (!update?.needsUpdate || !update.remoteVersion) return;
+  const hasStaleInstalledSkill = installedSdkSkillHasStalePositionalExecuteExamples();
+  if (!update?.needsUpdate && !hasStaleInstalledSkill || !update?.remoteVersion) {
+    return;
+  }
   writeSdkSkillsStatusLine("SDK skills changed; syncing deepline-sdk skill...");
   const installed = await runSkillsInstall(baseUrl);
   if (!installed) return;
+  if (installedSdkSkillHasStalePositionalExecuteExamples()) {
+    process.stderr.write(
+      "SDK skills sync completed, but installed deepline-sdk docs still contain stale positional ctx.tools.execute examples.\n"
+    );
+    return;
+  }
   writeLocalSkillsVersion(baseUrl, update.remoteVersion);
   writeSdkSkillsStatusLine("SDK skills are up to date.");
 }