deepline 0.1.33 → 0.1.35

package/dist/cli/index.js

@@ -216,8 +216,8 @@ function resolveConfig(options) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.33";
-var SDK_API_CONTRACT = "2026-05-host-env-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";
@@ -299,7 +299,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);
@@ -382,10 +382,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) {
@@ -435,6 +438,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) {
@@ -498,15 +521,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") {
@@ -772,13 +797,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 },
@@ -1076,34 +1104,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;
   }
@@ -1892,6 +1923,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)}
 `);
@@ -2068,7 +2196,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) {
@@ -3268,10 +3396,12 @@ function writeCanonicalRowsCsv(rowsInfo, outPath) {
     rows: rowsInfo.rows,
     columns: rowsInfo.columns
   });
+  const rows = dataExportRows(sanitized.rows);
+  const columns = dataExportColumns(rows, sanitized.columns);
   const resolved = (0, import_node_path5.resolve)(outPath);
   (0, import_node_fs4.writeFileSync)(
     resolved,
-    csvStringFromRows(sanitized.rows, sanitized.columns),
+    csvStringFromRows(rows, columns),
     "utf-8"
   );
   return resolved;
@@ -3392,6 +3522,14 @@ Examples:
 }
 
 // src/cli/commands/db.ts
+var import_node_fs5 = require("fs");
+var import_node_path6 = require("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) {
@@ -3405,10 +3543,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));
@@ -3442,22 +3578,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 = (0, import_node_path6.resolve)(outPath);
+  (0, import_node_fs5.writeFileSync)(
+    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 = (0, import_node_path6.resolve)(outPath);
+      (0, import_node_fs5.writeFileSync)(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 },
@@ -3465,7 +3725,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) {
@@ -3475,11 +3735,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(
@@ -3488,17 +3751,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"] : []
     ]);
   });
@@ -3674,21 +3943,21 @@ Examples:
 
 // src/cli/commands/play.ts
 var import_node_crypto3 = require("crypto");
-var import_node_fs7 = require("fs");
-var import_node_path9 = require("path");
+var import_node_fs8 = require("fs");
+var import_node_path10 = require("path");
 
 // src/plays/bundle-play-file.ts
 var import_node_os5 = require("os");
-var import_node_path8 = require("path");
+var import_node_path9 = require("path");
 var import_node_url = require("url");
-var import_node_fs6 = require("fs");
+var import_node_fs7 = require("fs");
 
 // ../shared_libs/plays/bundling/index.ts
 var import_node_crypto = require("crypto");
-var import_node_fs5 = require("fs");
+var import_node_fs6 = require("fs");
 var import_promises3 = require("fs/promises");
 var import_node_os4 = require("os");
-var import_node_path6 = require("path");
+var import_node_path7 = require("path");
 var import_node_module = require("module");
 var import_esbuild = require("esbuild");
 
@@ -3747,7 +4016,7 @@ function buildPlayContractCompatibility(input) {
 var PLAY_BUNDLE_CACHE_VERSION = 24;
 var MAX_PLAY_BUNDLE_BYTES = 30 * 1024 * 1024;
 var MAX_ESM_WORKERS_BUNDLE_BYTES = 115e4;
-var PLAY_ARTIFACT_CACHE_DIR = (0, import_node_path6.join)(
+var PLAY_ARTIFACT_CACHE_DIR = (0, import_node_path7.join)(
   (0, import_node_os4.tmpdir)(),
   `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`
 );
@@ -3780,13 +4049,13 @@ async function normalizeLocalPath(filePath) {
   try {
     return await (0, import_promises3.realpath)(filePath);
   } catch {
-    return (0, import_node_path6.resolve)(filePath);
+    return (0, import_node_path7.resolve)(filePath);
   }
 }
 function createPlayWorkspace(entryFile) {
   return {
     entryFile,
-    rootDir: (0, import_node_path6.dirname)(entryFile)
+    rootDir: (0, import_node_path7.dirname)(entryFile)
   };
 }
 function isPathInsideDirectory(filePath, directory) {
@@ -3939,7 +4208,7 @@ function extractDefinedPlayName(sourceCode) {
 }
 function readPackageVersionFromPackageJson(packageJsonPath, packageName) {
   try {
-    const packageJson = JSON.parse((0, import_node_fs5.readFileSync)(packageJsonPath, "utf-8"));
+    const packageJson = JSON.parse((0, import_node_fs6.readFileSync)(packageJsonPath, "utf-8"));
     if (packageJson.name === packageName && typeof packageJson.version === "string") {
       return packageJson.version;
     }
@@ -3949,18 +4218,18 @@ function readPackageVersionFromPackageJson(packageJsonPath, packageName) {
   return null;
 }
 function findPackageJsonPathFrom(startDir, packageName) {
-  let current = (0, import_node_path6.resolve)(startDir);
+  let current = (0, import_node_path7.resolve)(startDir);
   while (true) {
-    const packageJsonPath = (0, import_node_path6.join)(
+    const packageJsonPath = (0, import_node_path7.join)(
       current,
       "node_modules",
       packageName,
       "package.json"
     );
-    if ((0, import_node_fs5.existsSync)(packageJsonPath)) {
+    if ((0, import_node_fs6.existsSync)(packageJsonPath)) {
       return packageJsonPath;
     }
-    const parent = (0, import_node_path6.dirname)(current);
+    const parent = (0, import_node_path7.dirname)(current);
     if (parent === current) {
       return null;
     }
@@ -3969,29 +4238,29 @@ function findPackageJsonPathFrom(startDir, packageName) {
 }
 function findPackageJsonPath(packageName, fromFile, adapter) {
   const startDirs = [
-    (0, import_node_path6.dirname)(fromFile),
+    (0, import_node_path7.dirname)(fromFile),
     adapter.projectRoot,
-    (0, import_node_path6.dirname)(adapter.sdkPackageJson),
+    (0, import_node_path7.dirname)(adapter.sdkPackageJson),
     process.cwd()
   ];
   const seen = /* @__PURE__ */ new Set();
   for (const startDir of startDirs) {
-    const normalized = (0, import_node_path6.resolve)(startDir);
+    const normalized = (0, import_node_path7.resolve)(startDir);
     if (seen.has(normalized)) continue;
     seen.add(normalized);
     const packageJsonPath = findPackageJsonPathFrom(normalized, packageName);
     if (packageJsonPath) return packageJsonPath;
   }
-  const adapterNodeModulesPackageJson = (0, import_node_path6.join)(
+  const adapterNodeModulesPackageJson = (0, import_node_path7.join)(
     adapter.nodeModulesDir,
     packageName,
     "package.json"
   );
-  return (0, import_node_fs5.existsSync)(adapterNodeModulesPackageJson) ? adapterNodeModulesPackageJson : null;
+  return (0, import_node_fs6.existsSync)(adapterNodeModulesPackageJson) ? adapterNodeModulesPackageJson : null;
 }
 function localSdkAliasPlugin(adapter, options) {
   const entryFile = options?.workersRuntime ? adapter.sdkWorkersEntryFile : adapter.sdkEntryFile;
-  if (!(0, import_node_fs5.existsSync)(entryFile)) {
+  if (!(0, import_node_fs6.existsSync)(entryFile)) {
     return null;
   }
   return {
@@ -4031,7 +4300,7 @@ function workersNamedPlayEntryAliasPlugin(playFilePath, exportName) {
           contents: `export { ${exportName} as default } from ${JSON.stringify(playFilePath)};
 `,
           loader: "ts",
-          resolveDir: (0, import_node_path6.dirname)(playFilePath)
+          resolveDir: (0, import_node_path7.dirname)(playFilePath)
         })
       );
     }
@@ -4195,7 +4464,7 @@ function importedPlayProxyPlugin(importedPlayDependencies) {
         return {
           contents: buildImportedPlayProxyModule(dependency.playName),
           loader: "ts",
-          resolveDir: (0, import_node_path6.dirname)(args.path)
+          resolveDir: (0, import_node_path7.dirname)(args.path)
         };
       });
     }
@@ -4213,12 +4482,12 @@ async function resolveLocalImport(fromFile, specifier) {
   if (specifier.startsWith("file:")) {
     return normalizeLocalPath(new URL(specifier).pathname);
   }
-  const base = (0, import_node_path6.isAbsolute)(specifier) ? (0, import_node_path6.resolve)(specifier) : (0, import_node_path6.resolve)((0, import_node_path6.dirname)(fromFile), specifier);
+  const base = (0, import_node_path7.isAbsolute)(specifier) ? (0, import_node_path7.resolve)(specifier) : (0, import_node_path7.resolve)((0, import_node_path7.dirname)(fromFile), specifier);
   const candidates = [base];
-  const explicitExtension = (0, import_node_path6.extname)(base).toLowerCase();
+  const explicitExtension = (0, import_node_path7.extname)(base).toLowerCase();
   if (!explicitExtension) {
     candidates.push(...SOURCE_EXTENSIONS.map((extension) => `${base}${extension}`));
-    candidates.push(...SOURCE_EXTENSIONS.map((extension) => (0, import_node_path6.join)(base, `index${extension}`)));
+    candidates.push(...SOURCE_EXTENSIONS.map((extension) => (0, import_node_path7.join)(base, `index${extension}`)));
   } else if ([".js", ".jsx", ".mjs", ".cjs"].includes(explicitExtension)) {
     const stem = base.slice(0, -explicitExtension.length);
     candidates.push(...SOURCE_EXTENSIONS.map((extension) => `${stem}${extension}`));
@@ -4232,9 +4501,9 @@ async function resolveLocalImport(fromFile, specifier) {
 }
 function resolvePackageImport(specifier, fromFile, adapter) {
   const packageName = getPackageName(specifier);
-  if (packageName === "deepline" && (0, import_node_fs5.existsSync)(adapter.sdkPackageJson)) {
+  if (packageName === "deepline" && (0, import_node_fs6.existsSync)(adapter.sdkPackageJson)) {
     const packageJson = JSON.parse(
-      (0, import_node_fs5.readFileSync)(adapter.sdkPackageJson, "utf-8")
+      (0, import_node_fs6.readFileSync)(adapter.sdkPackageJson, "utf-8")
     );
     return {
       name: "deepline",
@@ -4266,7 +4535,7 @@ async function analyzeSourceGraph(entryFile, adapter) {
     visited.add(absolutePath);
     const sourceCode2 = await (0, import_promises3.readFile)(absolutePath, "utf-8");
     localFiles.set(absolutePath, sourceCode2);
-    if ((0, import_node_path6.extname)(absolutePath).toLowerCase() === ".json") {
+    if ((0, import_node_path7.extname)(absolutePath).toLowerCase() === ".json") {
       return;
     }
     const handleSpecifier = async (specifier, line, column, kind) => {
@@ -4370,13 +4639,13 @@ async function computeWorkersHarnessFingerprintWithAdapter(adapter) {
   const tsFiles = entries.filter((e) => e.isFile() && /\.[cm]?ts$/.test(e.name)).map((e) => e.name).sort();
   const parts = [];
   for (const name of tsFiles) {
-    const contents = await (0, import_promises3.readFile)((0, import_node_path6.join)(adapter.workersHarnessFilesDir, name), "utf-8");
+    const contents = await (0, import_promises3.readFile)((0, import_node_path7.join)(adapter.workersHarnessFilesDir, name), "utf-8");
     parts.push({ name, hash: sha256(contents) });
   }
   return sha256(JSON.stringify(parts));
 }
 function artifactCachePath(graphHash, artifactKind, adapter) {
-  return (0, import_node_path6.join)(
+  return (0, import_node_path7.join)(
     adapter.cacheDir ?? PLAY_ARTIFACT_CACHE_DIR,
     `${graphHash}.${artifactKind}.json`
   );
@@ -4411,7 +4680,7 @@ function normalizeSourceMapForRuntime(sourceMapText) {
     if (sourcePath.startsWith("data:") || sourcePath.startsWith("node:") || sourcePath.startsWith("/") || /^[a-zA-Z]+:\/\//.test(sourcePath)) {
       return sourcePath;
     }
-    return (0, import_node_path6.resolve)(process.cwd(), sourcePath);
+    return (0, import_node_path7.resolve)(process.cwd(), sourcePath);
   });
   parsed.sourceRoot = void 0;
   return JSON.stringify(parsed);
@@ -4443,8 +4712,8 @@ async function runEsbuildForCjsNode(entryFile, importedPlayDependencies, adapter
     ...namedExportShim ? {
       stdin: {
         contents: namedExportShim,
-        resolveDir: (0, import_node_path6.dirname)(entryFile),
-        sourcefile: `${(0, import_node_path6.basename)(entryFile)}.${exportName}.entry.ts`,
+        resolveDir: (0, import_node_path7.dirname)(entryFile),
+        sourcefile: `${(0, import_node_path7.basename)(entryFile)}.${exportName}.entry.ts`,
         loader: "ts"
       }
     } : { entryPoints: [entryFile] },
@@ -4620,10 +4889,10 @@ workers-harness:${harnessFingerprint}`
     }
     const { bundledCode, sourceMapText, outputExtension } = buildOutcome;
     const normalizedSourceMap = normalizeSourceMapForRuntime(sourceMapText);
-    const virtualBaseName = exportName === "default" ? (0, import_node_path6.basename)(absolutePath).replace(/\.[^.]+$/, "") : `${(0, import_node_path6.basename)(absolutePath).replace(/\.[^.]+$/, "")}.${exportName}`;
+    const virtualBaseName = exportName === "default" ? (0, import_node_path7.basename)(absolutePath).replace(/\.[^.]+$/, "") : `${(0, import_node_path7.basename)(absolutePath).replace(/\.[^.]+$/, "")}.${exportName}`;
     const virtualFilename = `/virtual/deepline-plays/${analysis.graphHash}/${virtualBaseName}.${outputExtension}`;
     const executableCode = `${bundledCode}
-//# sourceMappingURL=${(0, import_node_path6.basename)(virtualFilename)}.map
+//# sourceMappingURL=${(0, import_node_path7.basename)(virtualFilename)}.map
 `;
     const bundleSizeError = getBundleSizeError(
       absolutePath,
@@ -4733,13 +5002,13 @@ function resolveExecutionProfile(override) {
 // src/plays/local-file-discovery.ts
 var import_node_crypto2 = require("crypto");
 var import_promises4 = require("fs/promises");
-var import_node_path7 = require("path");
+var import_node_path8 = require("path");
 var SOURCE_EXTENSIONS2 = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs", ".json"];
 function sha2562(buffer) {
   return (0, import_node_crypto2.createHash)("sha256").update(buffer).digest("hex");
 }
 function contentTypeForFile(filePath) {
-  const extension = (0, import_node_path7.extname)(filePath).toLowerCase();
+  const extension = (0, import_node_path8.extname)(filePath).toLowerCase();
   if (extension === ".csv") return "text/csv";
   if (extension === ".json") return "application/json";
   if (extension === ".txt") return "text/plain";
@@ -4930,16 +5199,16 @@ async function fileExists2(filePath) {
   }
 }
 function isPathInsideDirectory2(filePath, directory) {
-  const relativePath = (0, import_node_path7.relative)(directory, filePath);
-  return relativePath === "" || !relativePath.startsWith("..") && !(0, import_node_path7.isAbsolute)(relativePath);
+  const relativePath = (0, import_node_path8.relative)(directory, filePath);
+  return relativePath === "" || !relativePath.startsWith("..") && !(0, import_node_path8.isAbsolute)(relativePath);
 }
 async function resolveLocalImport2(fromFile, specifier) {
-  const base = (0, import_node_path7.isAbsolute)(specifier) ? (0, import_node_path7.resolve)(specifier) : (0, import_node_path7.resolve)((0, import_node_path7.dirname)(fromFile), specifier);
+  const base = (0, import_node_path8.isAbsolute)(specifier) ? (0, import_node_path8.resolve)(specifier) : (0, import_node_path8.resolve)((0, import_node_path8.dirname)(fromFile), specifier);
   const candidates = [base];
-  const explicitExtension = (0, import_node_path7.extname)(base).toLowerCase();
+  const explicitExtension = (0, import_node_path8.extname)(base).toLowerCase();
   if (!explicitExtension) {
     candidates.push(...SOURCE_EXTENSIONS2.map((extension) => `${base}${extension}`));
-    candidates.push(...SOURCE_EXTENSIONS2.map((extension) => (0, import_node_path7.join)(base, `index${extension}`)));
+    candidates.push(...SOURCE_EXTENSIONS2.map((extension) => (0, import_node_path8.join)(base, `index${extension}`)));
   } else if ([".js", ".jsx", ".mjs", ".cjs"].includes(explicitExtension)) {
     const stem = base.slice(0, -explicitExtension.length);
     candidates.push(...SOURCE_EXTENSIONS2.map((extension) => `${stem}${extension}`));
@@ -4952,13 +5221,13 @@ async function resolveLocalImport2(fromFile, specifier) {
   throw new Error(`Could not resolve local import "${specifier}" from ${fromFile}`);
 }
 async function discoverPackagedLocalFiles(entryFile) {
-  const absoluteEntryFile = (0, import_node_path7.resolve)(entryFile);
-  const packagingRoot = (0, import_node_path7.dirname)(absoluteEntryFile);
+  const absoluteEntryFile = (0, import_node_path8.resolve)(entryFile);
+  const packagingRoot = (0, import_node_path8.dirname)(absoluteEntryFile);
   const files = /* @__PURE__ */ new Map();
   const unresolved = [];
   const visitedFiles = /* @__PURE__ */ new Set();
   const visitSourceFile = async (filePath) => {
-    const absolutePath = (0, import_node_path7.resolve)(filePath);
+    const absolutePath = (0, import_node_path8.resolve)(filePath);
     if (visitedFiles.has(absolutePath)) {
       return;
     }
@@ -4990,8 +5259,8 @@ 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 = (0, import_node_path7.resolve)((0, import_node_path7.dirname)(absolutePath), resolvedPath);
-          if ((0, import_node_path7.isAbsolute)(resolvedPath) || !isPathInsideDirectory2(absoluteCsvPath, packagingRoot)) {
+          const absoluteCsvPath = (0, import_node_path8.resolve)((0, import_node_path8.dirname)(absolutePath), resolvedPath);
+          if ((0, import_node_path8.isAbsolute)(resolvedPath) || !isPathInsideDirectory2(absoluteCsvPath, packagingRoot)) {
             unresolved.push({
               sourceFragment: sourceCode.slice(argument.start, argument.end).trim(),
               message: "ctx.csv(...) packaged file paths must be relative paths inside the play directory. Pass external files at runtime with input.file instead."
@@ -5030,24 +5299,24 @@ async function discoverPackagedLocalFiles(entryFile) {
 // src/plays/bundle-play-file.ts
 var import_meta = {};
 var PLAY_BUNDLE_CACHE_VERSION2 = 30;
-var MODULE_DIR = (0, import_node_path8.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
-var SDK_PACKAGE_ROOT = (0, import_node_path8.resolve)(MODULE_DIR, "..", "..");
-var SOURCE_REPO_ROOT = (0, import_node_path8.resolve)(SDK_PACKAGE_ROOT, "..");
-var HAS_SOURCE_BUNDLING_SOURCES = (0, import_node_fs6.existsSync)(
-  (0, import_node_path8.resolve)(SOURCE_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
+var MODULE_DIR = (0, import_node_path9.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+var SDK_PACKAGE_ROOT = (0, import_node_path9.resolve)(MODULE_DIR, "..", "..");
+var SOURCE_REPO_ROOT = (0, import_node_path9.resolve)(SDK_PACKAGE_ROOT, "..");
+var HAS_SOURCE_BUNDLING_SOURCES = (0, import_node_fs7.existsSync)(
+  (0, import_node_path9.resolve)(SOURCE_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
 );
-var PACKAGED_REPO_ROOT = (0, import_node_path8.resolve)(SDK_PACKAGE_ROOT, "dist", "repo");
-var HAS_PACKAGED_BUNDLING_SOURCES = (0, import_node_fs6.existsSync)(
-  (0, import_node_path8.resolve)(PACKAGED_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
+var PACKAGED_REPO_ROOT = (0, import_node_path9.resolve)(SDK_PACKAGE_ROOT, "dist", "repo");
+var HAS_PACKAGED_BUNDLING_SOURCES = (0, import_node_fs7.existsSync)(
+  (0, import_node_path9.resolve)(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 : (0, import_node_path8.resolve)(SDK_PACKAGE_ROOT, "..");
-var SDK_SOURCE_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? (0, import_node_path8.resolve)(SOURCE_REPO_ROOT, "sdk", "src") : HAS_PACKAGED_BUNDLING_SOURCES ? (0, import_node_path8.resolve)(PACKAGED_REPO_ROOT, "sdk", "src") : (0, import_node_path8.resolve)(SDK_PACKAGE_ROOT, "src");
-var SDK_PACKAGE_JSON = (0, import_node_path8.resolve)(SDK_PACKAGE_ROOT, "package.json");
-var SDK_ENTRY_FILE = (0, import_node_path8.resolve)(SDK_SOURCE_ROOT, "index.ts");
-var SDK_TYPES_ENTRY_FILE = HAS_SOURCE_BUNDLING_SOURCES ? SDK_ENTRY_FILE : (0, import_node_path8.resolve)(SDK_PACKAGE_ROOT, "dist", "index.d.ts");
-var SDK_WORKERS_ENTRY_FILE = (0, import_node_path8.resolve)(SDK_SOURCE_ROOT, "worker-play-entry.ts");
-var WORKERS_HARNESS_ENTRY_FILE = (0, import_node_path8.resolve)(PROJECT_ROOT, "apps", "play-runner-workers", "src", "entry.ts");
-var WORKERS_HARNESS_FILES_DIR = (0, import_node_path8.resolve)(PROJECT_ROOT, "apps", "play-runner-workers", "src");
+var PROJECT_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? SOURCE_REPO_ROOT : HAS_PACKAGED_BUNDLING_SOURCES ? PACKAGED_REPO_ROOT : (0, import_node_path9.resolve)(SDK_PACKAGE_ROOT, "..");
+var SDK_SOURCE_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? (0, import_node_path9.resolve)(SOURCE_REPO_ROOT, "sdk", "src") : HAS_PACKAGED_BUNDLING_SOURCES ? (0, import_node_path9.resolve)(PACKAGED_REPO_ROOT, "sdk", "src") : (0, import_node_path9.resolve)(SDK_PACKAGE_ROOT, "src");
+var SDK_PACKAGE_JSON = (0, import_node_path9.resolve)(SDK_PACKAGE_ROOT, "package.json");
+var SDK_ENTRY_FILE = (0, import_node_path9.resolve)(SDK_SOURCE_ROOT, "index.ts");
+var SDK_TYPES_ENTRY_FILE = HAS_SOURCE_BUNDLING_SOURCES ? SDK_ENTRY_FILE : (0, import_node_path9.resolve)(SDK_PACKAGE_ROOT, "dist", "index.d.ts");
+var SDK_WORKERS_ENTRY_FILE = (0, import_node_path9.resolve)(SDK_SOURCE_ROOT, "worker-play-entry.ts");
+var WORKERS_HARNESS_ENTRY_FILE = (0, import_node_path9.resolve)(PROJECT_ROOT, "apps", "play-runner-workers", "src", "entry.ts");
+var WORKERS_HARNESS_FILES_DIR = (0, import_node_path9.resolve)(PROJECT_ROOT, "apps", "play-runner-workers", "src");
 var hasWarnedAboutNonDevelopmentBundling = false;
 function warnAboutNonDevelopmentBundling(filePath) {
   if (hasWarnedAboutNonDevelopmentBundling) {
@@ -5071,12 +5340,12 @@ function defaultPlayBundleTarget() {
 function createSdkPlayBundlingAdapter() {
   return {
     projectRoot: PROJECT_ROOT,
-    nodeModulesDir: (0, import_node_path8.resolve)(PROJECT_ROOT, "node_modules"),
-    cacheDir: (0, import_node_path8.join)((0, import_node_os5.tmpdir)(), `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION2}`),
+    nodeModulesDir: (0, import_node_path9.resolve)(PROJECT_ROOT, "node_modules"),
+    cacheDir: (0, import_node_path9.join)((0, import_node_os5.tmpdir)(), `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION2}`),
     sdkSourceRoot: SDK_SOURCE_ROOT,
     sdkPackageJson: SDK_PACKAGE_JSON,
     sdkEntryFile: SDK_ENTRY_FILE,
-    sdkTypesEntryFile: HAS_SOURCE_BUNDLING_SOURCES || !(0, import_node_fs6.existsSync)(SDK_TYPES_ENTRY_FILE) ? SDK_ENTRY_FILE : SDK_TYPES_ENTRY_FILE,
+    sdkTypesEntryFile: HAS_SOURCE_BUNDLING_SOURCES || !(0, import_node_fs7.existsSync)(SDK_TYPES_ENTRY_FILE) ? SDK_ENTRY_FILE : SDK_TYPES_ENTRY_FILE,
     sdkWorkersEntryFile: SDK_WORKERS_ENTRY_FILE,
     workersHarnessEntryFile: WORKERS_HARNESS_ENTRY_FILE,
     workersHarnessFilesDir: WORKERS_HARNESS_FILES_DIR,
@@ -5309,7 +5578,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();
@@ -5355,7 +5624,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 (0, import_node_path9.resolve)(`${safeName || "play"}.play.ts`);
+  return (0, import_node_path10.resolve)(`${safeName || "play"}.play.ts`);
 }
 function materializeRemotePlaySource(input) {
   if (isFileTarget(input.target)) {
@@ -5365,15 +5634,15 @@ function materializeRemotePlaySource(input) {
     return null;
   }
   const outputPath = input.outPath ?? defaultMaterializedPlayPath(input.playName);
-  if ((0, import_node_fs7.existsSync)(outputPath)) {
-    const existingSource = (0, import_node_fs7.readFileSync)(outputPath, "utf-8");
+  if ((0, import_node_fs8.existsSync)(outputPath)) {
+    const existingSource = (0, import_node_fs8.readFileSync)(outputPath, "utf-8");
     if (existingSource === input.sourceCode) {
       return { path: outputPath, status: "unchanged", created: false };
     }
-    (0, import_node_fs7.writeFileSync)(outputPath, input.sourceCode, "utf-8");
+    (0, import_node_fs8.writeFileSync)(outputPath, input.sourceCode, "utf-8");
     return { path: outputPath, status: "updated", created: false };
   }
-  (0, import_node_fs7.writeFileSync)(outputPath, input.sourceCode, "utf-8");
+  (0, import_node_fs8.writeFileSync)(outputPath, input.sourceCode, "utf-8");
   return { path: outputPath, status: "created", created: true };
 }
 function formatLoadedPlayMessage(materializedFile) {
@@ -5418,7 +5687,7 @@ function extractPlayName(code, filePath) {
   throw buildMissingDefinePlayError(filePath);
 }
 function isFileTarget(target) {
-  return (0, import_node_fs7.existsSync)((0, import_node_path9.resolve)(target));
+  return (0, import_node_fs8.existsSync)((0, import_node_path10.resolve)(target));
 }
 function looksLikeFilePath(target) {
   if (target.trim().toLowerCase().startsWith("prebuilt/")) {
@@ -5437,7 +5706,7 @@ function parsePositiveInteger2(value, flagName) {
   return parsed;
 }
 function parseJsonInput(raw) {
-  const source = raw.startsWith("@") ? (0, import_node_fs7.readFileSync)((0, import_node_path9.resolve)(raw.slice(1)), "utf-8") : raw;
+  const source = raw.startsWith("@") ? (0, import_node_fs8.readFileSync)((0, import_node_path10.resolve)(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.");
@@ -5538,7 +5807,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 (0, import_node_fs7.existsSync)((0, import_node_path9.resolve)(value));
+  return (0, import_node_fs8.existsSync)((0, import_node_path10.resolve)(value));
 }
 function inputContainsLocalFilePath(value) {
   if (isLocalFilePathValue(value)) {
@@ -5564,8 +5833,8 @@ async function stageFileInputArgs(input) {
   const localFiles = uniqueBindings.flatMap((binding) => {
     const value = getDottedInputValue(input.runtimeInput, binding.inputPath);
     if (!isLocalFilePathValue(value)) return [];
-    const absolutePath = (0, import_node_path9.resolve)(value);
-    return [{ binding, absolutePath, logicalPath: (0, import_node_path9.basename)(absolutePath) }];
+    const absolutePath = (0, import_node_path10.resolve)(value);
+    return [{ binding, absolutePath, logicalPath: (0, import_node_path10.basename)(absolutePath) }];
   });
   if (localFiles.length === 0) {
     return { inputFile: null, packagedFiles: [] };
@@ -5589,7 +5858,7 @@ async function stageFileInputArgs(input) {
   };
 }
 function stageFile(logicalPath, absolutePath) {
-  const buffer = (0, import_node_fs7.readFileSync)(absolutePath);
+  const buffer = (0, import_node_fs8.readFileSync)(absolutePath);
   return {
     logicalPath,
     contentBase64: buffer.toString("base64"),
@@ -5600,9 +5869,9 @@ function stageFile(logicalPath, absolutePath) {
 }
 function normalizePlayPath(filePath) {
   try {
-    return import_node_fs7.realpathSync.native((0, import_node_path9.resolve)(filePath));
+    return import_node_fs8.realpathSync.native((0, import_node_path10.resolve)(filePath));
   } catch {
-    return (0, import_node_path9.resolve)(filePath);
+    return (0, import_node_path10.resolve)(filePath);
   }
 }
 function formatBundlingErrors(filePath, errors) {
@@ -5755,11 +6024,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 : {};
 }
@@ -5921,6 +6221,34 @@ 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,
@@ -6247,14 +6575,23 @@ function buildRunWarnings(status, rowsInfo) {
   }
   return [];
 }
-function buildRunNextCommands(runId, dashboardUrl) {
+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 (dashboardUrl) {
-    commands.open = `Open ${dashboardUrl} to see results.`;
+  if (status.dashboardUrl) {
+    commands.open = `Open ${status.dashboardUrl} to see results.`;
   }
   return commands;
 }
@@ -6277,6 +6614,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 {
@@ -6327,18 +6779,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
     }
   ];
 }
@@ -6387,6 +6854,7 @@ 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,
@@ -6399,13 +6867,13 @@ function compactPlayStatus(status) {
     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, status.dashboardUrl)
+    next: buildRunNextCommands(status)
   };
 }
 function enrichPlayStatusWithDatasetStats(status) {
@@ -6479,7 +6947,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) {
@@ -6503,8 +6972,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((0, import_node_path9.resolve)(outPath))}`;
+  return `deepline runs export ${runId}${datasetPath ? ` --dataset ${shellSingleQuote(datasetPath)}` : ""} --out ${shellSingleQuote((0, import_node_path10.resolve)(outPath))}`;
 }
 function extractRunPlayName(status) {
   const run = status.run;
@@ -6521,6 +6993,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((0, import_node_path10.resolve)(input.outPath))}`
+  };
+}
 function exportableSheetRow(row) {
   if (!row || typeof row !== "object" || Array.isArray(row)) {
     return null;
@@ -6692,6 +7184,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: [] };
@@ -6927,12 +7473,12 @@ function shouldUseLocalOnlyPlayCheck() {
 async function handlePlayCheck(args) {
   const options = parsePlayCheckOptions(args);
   if (!isFileTarget(options.target)) {
-    const resolved = (0, import_node_path9.resolve)(options.target);
+    const resolved = (0, import_node_path10.resolve)(options.target);
     console.error(`File not found: ${resolved}`);
     return 1;
   }
-  const absolutePlayPath = (0, import_node_path9.resolve)(options.target);
-  const sourceCode = (0, import_node_fs7.readFileSync)(absolutePlayPath, "utf-8");
+  const absolutePlayPath = (0, import_node_path10.resolve)(options.target);
+  const sourceCode = (0, import_node_fs8.readFileSync)(absolutePlayPath, "utf-8");
   let graph;
   try {
     graph = await collectBundledPlayGraph(absolutePlayPath);
@@ -6995,12 +7541,12 @@ async function handleFileBackedRun(options) {
   }
   const client = new DeeplineClient();
   const progress = getActiveCliProgress() ?? createCliProgress(!options.jsonOutput);
-  const absolutePlayPath = (0, import_node_path9.resolve)(options.target.path);
+  const absolutePlayPath = (0, import_node_path10.resolve)(options.target.path);
   progress.phase("compiling play");
   const sourceCode = traceCliSync(
     "cli.play_file_read_source",
     { targetKind: "file" },
-    () => (0, import_node_fs7.readFileSync)(absolutePlayPath, "utf-8")
+    () => (0, import_node_fs8.readFileSync)(absolutePlayPath, "utf-8")
   );
   const runtimeInput = options.input ? { ...options.input } : {};
   let graph;
@@ -7081,6 +7627,8 @@ async function handleFileBackedRun(options) {
         waitTimeoutMs: options.waitTimeoutMs,
         noOpen: options.noOpen,
         progress
+      }).catch((error) => {
+        throw normalizePlayStartError(error, playName);
       })
     );
     if (finalStatus.status === "completed") {
@@ -7099,7 +7647,9 @@ 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 resolvedDashboardUrl = buildPlayDashboardUrl(client.baseUrl, playName);
   openPlayDashboard({
@@ -7216,6 +7766,8 @@ async function handleNamedRun(options) {
         waitTimeoutMs: options.waitTimeoutMs,
         noOpen: options.noOpen,
         progress
+      }).catch((error) => {
+        throw normalizePlayStartError(error, playName);
       })
     );
     if (finalStatus.status === "completed") {
@@ -7234,7 +7786,9 @@ async function handleNamedRun(options) {
   const started = await traceCliSpan(
     "cli.play_start_unwatched",
     { targetKind: "name", playName },
-    () => client.startPlayRun(startRequest)
+    () => client.startPlayRun(startRequest).catch((error) => {
+      throw normalizePlayStartError(error, playName);
+    })
   );
   const resolvedDashboardUrl = buildPlayDashboardUrl(client.baseUrl, playName);
   openPlayDashboard({
@@ -7260,19 +7814,19 @@ async function handlePlayRun(args) {
     if (isFileTarget(options.target.path)) {
       return handleFileBackedRun(options);
     }
-    const resolved = (0, import_node_path9.resolve)(options.target.path);
+    const resolved = (0, import_node_path10.resolve)(options.target.path);
     console.error(`File not found: ${resolved}`);
-    const dir = (0, import_node_path9.dirname)(resolved);
-    if ((0, import_node_fs7.existsSync)(dir)) {
-      const base = (0, import_node_path9.basename)(resolved);
+    const dir = (0, import_node_path10.dirname)(resolved);
+    if ((0, import_node_fs8.existsSync)(dir)) {
+      const base = (0, import_node_path10.basename)(resolved);
       try {
-        const siblings = (0, import_node_fs7.readdirSync)(dir).filter(
+        const siblings = (0, import_node_fs8.readdirSync)(dir).filter(
           (f) => f.includes(base.replace(/\.(play\.)?ts$/, "")) || f.endsWith(".play.ts")
         );
         if (siblings.length > 0) {
           console.error(`Did you mean one of these?`);
           for (const s of siblings.slice(0, 5)) {
-            console.error(`  ${(0, import_node_path9.join)(dir, s)}`);
+            console.error(`  ${(0, import_node_path10.join)(dir, s)}`);
           }
         }
       } catch {
@@ -7407,14 +7961,14 @@ async function handleRunLogs(args) {
       continue;
     }
     if (arg === "--out" && args[index + 1]) {
-      outPath = (0, import_node_path9.resolve)(args[++index]);
+      outPath = (0, import_node_path10.resolve)(args[++index]);
     }
   }
   const client = new DeeplineClient();
   const status = await client.runs.get(runId);
   const logs = status.progress?.logs ?? [];
   if (outPath) {
-    (0, import_node_fs7.writeFileSync)(outPath, `${logs.join("\n")}${logs.length > 0 ? "\n" : ""}`);
+    (0, import_node_fs8.writeFileSync)(outPath, `${logs.join("\n")}${logs.length > 0 ? "\n" : ""}`);
     printCommandEnvelope({
       runId: status.runId,
       log_path: outPath,
@@ -7470,7 +8024,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);
@@ -7480,14 +8034,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 = (0, import_node_path9.resolve)(args[++index]);
+      outPath = (0, import_node_path10.resolve)(args[++index]);
       continue;
     }
     if (arg === "--dataset" && args[index + 1]) {
       datasetPath = args[++index];
+      continue;
+    }
+    if (arg === "--metadata-out" && args[index + 1]) {
+      metadataOutPath = (0, import_node_path10.resolve)(args[++index]);
     }
   }
   if (!outPath) {
@@ -7499,15 +8058,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) {
+    (0, import_node_fs8.writeFileSync)(
+      metadataOutPath,
+      `${JSON.stringify(payload, null, 2)}
+`,
+      "utf-8"
+    );
+  }
+  printCommandEnvelope(payload, { json: argsWantJson(args) });
   return 0;
 }
 async function handlePlayGet(args) {
@@ -7524,10 +8127,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 = (0, import_node_path9.resolve)(args[++index]);
+      outPath = (0, import_node_path10.resolve)(args[++index]);
     }
   }
-  const playName = isFileTarget(target) ? extractPlayName((0, import_node_fs7.readFileSync)((0, import_node_path9.resolve)(target), "utf-8"), (0, import_node_path9.resolve)(target)) : parseReferencedPlayTarget(target).playName;
+  const playName = isFileTarget(target) ? extractPlayName((0, import_node_fs8.readFileSync)((0, import_node_path10.resolve)(target), "utf-8"), (0, import_node_path10.resolve)(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({
@@ -7819,7 +8422,7 @@ async function handlePlayPublish(args) {
     }
     let graph;
     try {
-      graph = await collectBundledPlayGraph((0, import_node_path9.resolve)(playName));
+      graph = await collectBundledPlayGraph((0, import_node_path10.resolve)(playName));
       await compileBundledPlayGraphManifests(client, graph);
       await publishImportedPlayDependencies(client, graph);
     } catch (error) {
@@ -8305,32 +8908,36 @@ 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
-var import_node_fs9 = require("fs");
+var import_node_fs10 = require("fs");
 var import_node_os7 = require("os");
-var import_node_path11 = require("path");
+var import_node_path12 = require("path");
 
 // src/tool-output.ts
-var import_node_fs8 = require("fs");
+var import_node_fs9 = require("fs");
 var import_node_os6 = require("os");
-var import_node_path10 = require("path");
+var import_node_path11 = require("path");
 function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -8353,6 +8960,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)) {
@@ -8405,19 +9031,19 @@ function tryConvertToList(payload, options) {
   return null;
 }
 function ensureOutputDir() {
-  const outputDir = (0, import_node_path10.join)((0, import_node_os6.homedir)(), ".local", "share", "deepline", "data");
-  (0, import_node_fs8.mkdirSync)(outputDir, { recursive: true });
+  const outputDir = (0, import_node_path11.join)((0, import_node_os6.homedir)(), ".local", "share", "deepline", "data");
+  (0, import_node_fs9.mkdirSync)(outputDir, { recursive: true });
   return outputDir;
 }
 function writeJsonOutputFile(payload, stem) {
   const outputDir = ensureOutputDir();
-  const outputPath = (0, import_node_path10.join)(outputDir, `${stem}_${Date.now()}.json`);
-  (0, import_node_fs8.writeFileSync)(outputPath, JSON.stringify(payload, null, 2), "utf-8");
+  const outputPath = (0, import_node_path11.join)(outputDir, `${stem}_${Date.now()}.json`);
+  (0, import_node_fs9.writeFileSync)(outputPath, JSON.stringify(payload, null, 2), "utf-8");
   return outputPath;
 }
 function writeCsvOutputFile(rows, stem) {
   const outputDir = ensureOutputDir();
-  const outputPath = (0, import_node_path10.join)(outputDir, `${stem}_${Date.now()}.csv`);
+  const outputPath = (0, import_node_path11.join)(outputDir, `${stem}_${Date.now()}.csv`);
   const seen = /* @__PURE__ */ new Set();
   const columns = [];
   for (const row of rows) {
@@ -8440,7 +9066,7 @@ function writeCsvOutputFile(rows, stem) {
   for (const row of rows) {
     lines.push(columns.map((column) => escapeCell(row[column])).join(","));
   }
-  (0, import_node_fs8.writeFileSync)(outputPath, `${lines.join("\n")}
+  (0, import_node_fs9.writeFileSync)(outputPath, `${lines.join("\n")}
 `, "utf-8");
   const previewRows = rows.slice(0, 5);
   const previewColumns = columns.slice(0, 5);
@@ -8486,8 +9112,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}`];
         })
       }
     ]
@@ -8566,7 +9191,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.
 `
   );
@@ -8613,8 +9238,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
@@ -8627,7 +9252,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",
     `
@@ -8708,6 +9348,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:");
@@ -8771,14 +9412,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(", ")}`);
     }
@@ -8797,7 +9440,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;
@@ -8865,6 +9554,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"));
@@ -8938,6 +9638,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]) {
@@ -8964,6 +9665,7 @@ function parseExecuteOptions(args) {
     }
     if (arg === "--full-output") {
       outputFormat = "json";
+      fullOutput = true;
       continue;
     }
     if (arg === "--no-preview") {
@@ -8972,7 +9674,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";
@@ -8986,9 +9688,9 @@ function powerShellQuote(value) {
 function seedToolListScript(input) {
   const stem = safeFileStem(input.toolId);
   const fileName = `${stem}-workflow-seed-${Date.now()}.play.ts`;
-  const scriptDir = (0, import_node_fs9.mkdtempSync)((0, import_node_path11.join)((0, import_node_os7.tmpdir)(), "deepline-workflow-seed-"));
-  (0, import_node_fs9.chmodSync)(scriptDir, 448);
-  const scriptPath = (0, import_node_path11.join)(scriptDir, fileName);
+  const scriptDir = (0, import_node_fs10.mkdtempSync)((0, import_node_path12.join)((0, import_node_os7.tmpdir)(), "deepline-workflow-seed-"));
+  (0, import_node_fs10.chmodSync)(scriptDir, 448);
+  const scriptPath = (0, import_node_path12.join)(scriptDir, fileName);
   const projectDir = `deepline/projects/${stem}-workflow`;
   const playName = `${stem}-workflow`;
   const sampleRows = input.rows.length > 0 ? `${JSON.stringify(input.rows.slice(0, 2)).replace(/\]$/, "")}, ...]` : "[]";
@@ -9004,7 +9706,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}
@@ -9021,7 +9723,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   };
 });
 `;
-  (0, import_node_fs9.writeFileSync)(scriptPath, script, { encoding: "utf-8", mode: 384 });
+  (0, import_node_fs10.writeFileSync)(scriptPath, script, { encoding: "utf-8", mode: 384 });
   return {
     path: scriptPath,
     projectDir,
@@ -9032,7 +9734,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] ?? {}),
@@ -9043,6 +9745,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",
@@ -9051,7 +9754,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."
@@ -9104,8 +9807,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({
@@ -9236,8 +9943,8 @@ async function executeTool(args) {
 
 // src/cli/commands/update.ts
 var import_node_child_process = require("child_process");
-var import_node_fs10 = require("fs");
-var import_node_path12 = require("path");
+var import_node_fs11 = require("fs");
+var import_node_path13 = require("path");
 function posixShellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -9256,19 +9963,19 @@ function buildSourceUpdateCommand(sourceRoot) {
   return `${cdCommand} && git fetch origin main --tags && git merge --ff-only origin/main`;
 }
 function findRepoBackedSdkRoot(startPath) {
-  let current = (0, import_node_path12.resolve)(startPath);
+  let current = (0, import_node_path13.resolve)(startPath);
   while (true) {
-    if ((0, import_node_fs10.existsSync)((0, import_node_path12.join)(current, "sdk", "package.json")) && (0, import_node_fs10.existsSync)((0, import_node_path12.join)(current, "sdk", "bin", "deepline-dev.ts"))) {
+    if ((0, import_node_fs11.existsSync)((0, import_node_path13.join)(current, "sdk", "package.json")) && (0, import_node_fs11.existsSync)((0, import_node_path13.join)(current, "sdk", "bin", "deepline-dev.ts"))) {
       return current;
     }
-    const parent = (0, import_node_path12.dirname)(current);
+    const parent = (0, import_node_path13.dirname)(current);
     if (parent === current) return null;
     current = parent;
   }
 }
 function resolveUpdatePlan() {
-  const entrypoint = process.argv[1] ? (0, import_node_path12.resolve)(process.argv[1]) : "";
-  const sourceRoot = entrypoint ? findRepoBackedSdkRoot((0, import_node_path12.dirname)(entrypoint)) : null;
+  const entrypoint = process.argv[1] ? (0, import_node_path13.resolve)(process.argv[1]) : "";
+  const sourceRoot = entrypoint ? findRepoBackedSdkRoot((0, import_node_path13.dirname)(entrypoint)) : null;
   if (sourceRoot) {
     return {
       kind: "source",
@@ -9361,9 +10068,9 @@ Examples:
 
 // src/cli/skills-sync.ts
 var import_node_child_process2 = require("child_process");
-var import_node_fs11 = require("fs");
+var import_node_fs12 = require("fs");
 var import_node_os8 = require("os");
-var import_node_path13 = require("path");
+var import_node_path14 = require("path");
 var CHECK_TIMEOUT_MS2 = 3e3;
 var SDK_SKILL_NAME = "deepline-sdk";
 var SKILL_AGENTS = ["codex", "claude-code", "cursor"];
@@ -9374,23 +10081,59 @@ function shouldSkipSkillsSync() {
 }
 function sdkSkillsVersionPath(baseUrl) {
   const home = process.env.HOME?.trim() || (0, import_node_os8.homedir)();
-  return (0, import_node_path13.join)(home, ".local", "deepline", baseUrlSlug(baseUrl), "sdk-skills", ".version");
+  return (0, import_node_path14.join)(home, ".local", "deepline", baseUrlSlug(baseUrl), "sdk-skills", ".version");
 }
 function readLocalSkillsVersion(baseUrl) {
   const path = sdkSkillsVersionPath(baseUrl);
-  if (!(0, import_node_fs11.existsSync)(path)) return "";
+  if (!(0, import_node_fs12.existsSync)(path)) return "";
   try {
-    return (0, import_node_fs11.readFileSync)(path, "utf-8").trim();
+    return (0, import_node_fs12.readFileSync)(path, "utf-8").trim();
   } catch {
     return "";
   }
 }
 function writeLocalSkillsVersion(baseUrl, version) {
   const path = sdkSkillsVersionPath(baseUrl);
-  (0, import_node_fs11.mkdirSync)((0, import_node_path13.dirname)(path), { recursive: true });
-  (0, import_node_fs11.writeFileSync)(path, `${version}
+  (0, import_node_fs12.mkdirSync)((0, import_node_path14.dirname)(path), { recursive: true });
+  (0, import_node_fs12.writeFileSync)(path, `${version}
 `, "utf-8");
 }
+function installedSdkSkillHasStalePositionalExecuteExamples() {
+  const home = process.env.HOME?.trim() || (0, import_node_os8.homedir)();
+  const roots = [
+    (0, import_node_path14.join)(home, ".claude", "skills", SDK_SKILL_NAME),
+    (0, import_node_path14.join)(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 (0, import_node_fs12.readdirSync)(dir)) {
+      const path = (0, import_node_path14.join)(dir, entry);
+      const stat3 = (0, import_node_fs12.statSync)(path);
+      if (stat3.isDirectory()) {
+        if (scan(path)) return true;
+        continue;
+      }
+      if (!entry.endsWith(".md")) continue;
+      const text = (0, import_node_fs12.readFileSync)(path, "utf-8");
+      if (staleMarkers.some((marker) => text.includes(marker))) return true;
+    }
+    return false;
+  };
+  for (const root of roots) {
+    try {
+      if ((0, import_node_fs12.existsSync)(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);
@@ -9426,7 +10169,7 @@ function buildSkillsInstallArgs(baseUrl) {
     "skills",
     "add",
     packageUrl,
-    "--agents",
+    "--agent",
     ...SKILL_AGENTS,
     "--global",
     "--yes",
@@ -9442,7 +10185,7 @@ function buildBunxSkillsInstallArgs(baseUrl) {
     "skills",
     "add",
     packageUrl,
-    "--agents",
+    "--agent",
     ...SKILL_AGENTS,
     "--global",
     "--yes",
@@ -9482,7 +10225,7 @@ function resolveSkillsInstallCommands(baseUrl) {
   return [npxInstall];
 }
 function runOneSkillsInstall(install) {
-  return new Promise((resolve10) => {
+  return new Promise((resolve11) => {
     const child = (0, import_node_child_process2.spawn)(install.command, install.args, {
       stdio: ["ignore", "ignore", "pipe"],
       env: process.env
@@ -9492,7 +10235,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
@@ -9500,11 +10243,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
@@ -9543,10 +10286,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.");
 }