deepline 0.3.213 → 0.3.214

package/dist/cli/index.mjs

@@ -3046,7 +3046,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.213",
+  version: "0.3.214",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -3367,6 +3367,22 @@ function writeSdkSkillsLocalVersion(baseUrl, version, agents) {
   return complete;
 }
 
+// src/deployment-protection.ts
+function deploymentProtectionHeaders() {
+  const token = typeof process !== "undefined" ? process.env?.VERCEL_PROTECTION_BYPASS_TOKEN : void 0;
+  return token ? { "x-vercel-protection-bypass": token } : {};
+}
+var fetchWithDeploymentProtection = (input2, init) => {
+  const headers = new Headers(
+    input2 instanceof Request ? input2.headers : void 0
+  );
+  new Headers(init?.headers).forEach((value, name) => headers.set(name, value));
+  for (const [name, value] of Object.entries(deploymentProtectionHeaders())) {
+    headers.set(name, value);
+  }
+  return fetch(input2, { ...init, headers });
+};
+
 // ../play-runtime/coordinator-headers.ts
 var COORDINATOR_INTERNAL_TOKEN_HEADER = "x-deepline-internal-token";
 var COORDINATOR_URL_OVERRIDE_HEADER = "x-deepline-coordinator-url";
@@ -3749,16 +3765,13 @@ var HttpClient = class {
       "X-Deepline-SDK-Version": SDK_VERSION,
       "X-Deepline-API-Contract": SDK_API_CONTRACT,
       "X-Deepline-Run-Result-Shape": "canonical",
-      ...extra
+      ...extra,
+      ...deploymentProtectionHeaders()
     };
     const skillsVersion = this.readSkillsVersionHeader();
     if (skillsVersion) {
       headers["X-Deepline-Skills-Version"] = skillsVersion;
     }
-    const bypassToken = typeof process !== "undefined" ? process.env?.VERCEL_PROTECTION_BYPASS_TOKEN : void 0;
-    if (bypassToken) {
-      headers["x-vercel-protection-bypass"] = bypassToken;
-    }
     const playArtifactR2Prefix = typeof process !== "undefined" ? process.env?.DEEPLINE_PLAY_ARTIFACT_R2_PREFIX : void 0;
     if (playArtifactR2Prefix) {
       headers["x-deepline-play-artifact-r2-prefix"] = playArtifactR2Prefix;
@@ -4887,13 +4900,13 @@ function previewValue(value, input2) {
       ([, descriptor]) => descriptor.enumerable
     );
     const selected = entries.slice(0, DOCFLOW_NODE_IO_LIMITS.maxObjectFields);
-    const fields = {};
+    const fields2 = {};
     for (const [key, descriptor] of selected) {
       const safeKey = truncateUtf8(
         ledgerSafeDocflowPreviewKey(input2.redactor.redactString(key)),
         DOCFLOW_NODE_IO_LIMITS.maxStringBytes
       );
-      fields[safeKey] = "value" in descriptor ? previewValue(descriptor.value, {
+      fields2[safeKey] = "value" in descriptor ? previewValue(descriptor.value, {
         ...input2,
         depth: input2.depth + 1,
         key
@@ -4901,7 +4914,7 @@ function previewValue(value, input2) {
     }
     return {
       kind: "object",
-      fields,
+      fields: fields2,
       totalFields: entries.length,
       ...entries.length > selected.length ? { truncated: true } : {}
     };
@@ -5010,20 +5023,20 @@ function normalizePreview(value, depth) {
     };
   }
   if (value.kind === "object" && isRecord3(value.fields)) {
-    const fields = {};
+    const fields2 = {};
     for (const [key, field] of Object.entries(value.fields).slice(
       0,
       DOCFLOW_NODE_IO_LIMITS.maxObjectFields
     )) {
       const normalized = normalizePreview(field, depth + 1);
-      if (normalized) fields[ledgerSafeDocflowPreviewKey(key)] = normalized;
+      if (normalized) fields2[ledgerSafeDocflowPreviewKey(key)] = normalized;
     }
-    const totalFields = typeof value.totalFields === "number" && Number.isFinite(value.totalFields) ? Math.max(Object.keys(fields).length, Math.floor(value.totalFields)) : Object.keys(fields).length;
+    const totalFields = typeof value.totalFields === "number" && Number.isFinite(value.totalFields) ? Math.max(Object.keys(fields2).length, Math.floor(value.totalFields)) : Object.keys(fields2).length;
     return {
       kind: "object",
-      fields,
+      fields: fields2,
       totalFields,
-      ...value.truncated === true || totalFields > Object.keys(fields).length ? { truncated: true } : {}
+      ...value.truncated === true || totalFields > Object.keys(fields2).length ? { truncated: true } : {}
     };
   }
   return null;
@@ -7035,10 +7048,19 @@ function normalizePlayStatus(raw) {
     );
   }
   const runId = typeof raw.runId === "string" ? raw.runId : typeof raw.workflowId === "string" ? raw.workflowId : packageRun?.id ?? "";
+  const legacyOverview = runPackage?.overview ?? raw.overview;
+  const runStatus = runPackage?.runStatus ?? raw.runStatus;
   return {
     ...raw,
     runId,
-    ...runPackage ? { package: runPackage, outputs: runPackage.outputs } : {},
+    ...isRecord7(legacyOverview) ? {
+      overview: legacyOverview
+    } : {},
+    ...isRecord7(runStatus) ? { runStatus } : {},
+    ...runPackage ? {
+      package: runPackage,
+      outputs: runPackage.outputs
+    } : {},
     status
   };
 }
@@ -7220,18 +7242,6 @@ function playRunResultFromStatus(status, startedAt, fallbackRunId) {
     error: status.progress?.error ?? (status.status !== "completed" ? status.status : void 0)
   };
 }
-function playRunStatusFromState(state) {
-  return {
-    runId: state.runId,
-    status: state.status,
-    progress: {
-      status: state.status,
-      logs: state.logs,
-      ...state.error ? { error: state.error } : {}
-    },
-    ..."result" in state ? { result: state.result } : {}
-  };
-}
 var DeeplineClient = class _DeeplineClient {
   http;
   config;
@@ -7374,14 +7384,14 @@ var DeeplineClient = class _DeeplineClient {
   }
   compactSchema(schema) {
     if (!schema) return null;
-    const fields = Array.isArray(schema.fields) ? schema.fields.map(
+    const fields2 = Array.isArray(schema.fields) ? schema.fields.map(
       (field) => field && typeof field === "object" ? {
         name: String(field.name ?? ""),
         type: field.type ?? void 0,
         required: field.required ?? void 0
       } : null
     ).filter((field) => Boolean(field?.name)) : [];
-    return fields.length > 0 ? { fields } : schema;
+    return fields2.length > 0 ? { fields: fields2 } : schema;
   }
   schemaMetadata(schema, key) {
     if (!isRecord7(schema)) return null;
@@ -7568,6 +7578,12 @@ var DeeplineClient = class _DeeplineClient {
       options.includeSearchDebug ? "true" : "false"
     );
     params.set("search_mode", options.searchMode ?? "v2");
+    if (options.limit !== void 0) {
+      params.set("limit", String(options.limit));
+    }
+    if (options.offset !== void 0) {
+      params.set("offset", String(options.offset));
+    }
     if (options.categories?.trim()) {
       params.set("categories", options.categories.trim());
     }
@@ -8629,9 +8645,18 @@ var DeeplineClient = class _DeeplineClient {
     }
     const query = params.size > 0 ? `?${params.toString()}` : "";
     const response = await this.http.get(
-      `/api/v2/runs/${encodeURIComponent(runId)}${query}`
+      `/api/v2/runs/${encodeURIComponent(runId)}${query}`,
+      { headers: { "x-deepline-run-status": "1" } }
     );
+    const responseRunStatus = isPlayRunPackage(response) ? response.runStatus : isPlayRunPackage(response.package) ? response.package.runStatus : response.runStatus;
+    const responseOverview = isPlayRunPackage(response) ? response.overview : isPlayRunPackage(response.package) ? response.package.overview : response.overview;
     const status = normalizePlayStatus(response);
+    if (isRecord7(responseRunStatus)) {
+      status.runStatus = responseRunStatus;
+    }
+    if (isRecord7(responseOverview)) {
+      status.overview = responseOverview;
+    }
     if (options?.failedLogs !== true || status.status !== "failed") {
       return status;
     }
@@ -8672,7 +8697,10 @@ var DeeplineClient = class _DeeplineClient {
       }
     };
   }
-  /** Read only the bounded scalar projection; does not hydrate the run package. */
+  /** Fetch only the legacy scalar lifecycle status for a run.
+   *
+   * @deprecated Use `client.runs.get(runId)` for the canonical run read.
+   */
   async getRunLifecycleStatus(runId) {
     const response = await this.http.get(
       `/api/v2/runs/${encodeURIComponent(runId)}/status`
@@ -8848,9 +8876,7 @@ var DeeplineClient = class _DeeplineClient {
       if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {
         continue;
       }
-      return await this.getRunStatus(status.runId || runId).catch(
-        () => state.latest ?? playRunStatusFromState(state)
-      );
+      return await this.getRunStatus(status.runId || runId);
     }
     if (options?.signal?.aborted) {
       throw new DeeplineError("Run observation aborted.", void 0, "ABORTED");
@@ -8901,6 +8927,7 @@ var DeeplineClient = class _DeeplineClient {
     for (; ; ) {
       const connectedAt = Date.now();
       let sawEvent = false;
+      let terminalRunId = null;
       let endedReason = "stream window ended before a terminal event";
       try {
         for await (const event of this.streamPlayRunEvents(runId, {
@@ -8913,9 +8940,8 @@ var DeeplineClient = class _DeeplineClient {
           if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {
             continue;
           }
-          return await this.getRunStatus(status.runId || runId).catch(
-            () => state.latest ?? playRunStatusFromState(state)
-          );
+          terminalRunId = status.runId || runId;
+          break;
         }
       } catch (error) {
         if (options?.signal?.aborted || !isTransientPlayStreamError(error)) {
@@ -8923,15 +8949,11 @@ var DeeplineClient = class _DeeplineClient {
         }
         endedReason = error instanceof Error ? error.message : String(error);
       }
-      let refreshed = null;
-      try {
-        refreshed = await this.getRunStatus(runId);
-      } catch (error) {
-        if (!isTransientPlayStreamError(error)) {
-          throw error;
-        }
+      if (terminalRunId) {
+        return await this.getRunStatus(terminalRunId);
       }
-      if (refreshed && TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
+      const refreshed = await this.getRunStatus(runId);
+      if (TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
         return refreshed;
       }
       if (sawEvent || Date.now() - connectedAt >= STREAM_HEALTHY_CONNECTION_MS) {
@@ -9220,6 +9242,26 @@ var DeeplineClient = class _DeeplineClient {
       hasMore: Boolean(response.pagination?.hasMore ?? response.hasMore)
     };
   }
+  /** Read definition-level settings, independently of code revisions. */
+  async getPlaySettings(playName) {
+    return this.http.get(
+      `/api/v2/plays/${encodeURIComponent(playName)}/settings`
+    );
+  }
+  /** Retry-safe field patch; omitted fields retain their current value. */
+  async updatePlaySettings(playName, patch) {
+    return this.http.patch(
+      `/api/v2/plays/${encodeURIComponent(playName)}/settings`,
+      patch
+    );
+  }
+  /** List one bounded page of existing Play locations; continue with cursor. */
+  async listPlaySettingsPaths(options = {}) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(options))
+      if (value !== void 0) query.set(key, String(value));
+    return this.http.get(`/api/v2/plays/settings/paths?${query}`);
+  }
   /** Set whether an org-owned Play sorts before unpinned Plays. */
   async setPlayPinned(playName, pinned) {
     return this.http.post(`/api/v2/plays/${encodeURIComponent(playName)}/pin`, {
@@ -10837,6 +10879,7 @@ async function checkSdkCompatibility(baseUrl, options = {}) {
     const response = await fetch(url, {
       method: "GET",
       headers: {
+        ...deploymentProtectionHeaders(),
         "User-Agent": `deepline-ts-sdk/${SDK_VERSION}`,
         "X-Deepline-SDK-Version": SDK_VERSION,
         "X-Deepline-API-Major": String(SDK_API_MAJOR),
@@ -11713,8 +11756,8 @@ function resolvePendingAuthClaimForResume(baseUrl, requestedScope) {
     const claim = readPendingAuthClaim(baseUrl, requestedScope);
     return { claim, scope: claim?.scope ?? requestedScope };
   }
-  const folder = readPendingAuthClaim(baseUrl, "folder");
-  if (folder) return { claim: folder, scope: folder.scope };
+  const folder2 = readPendingAuthClaim(baseUrl, "folder");
+  if (folder2) return { claim: folder2, scope: folder2.scope };
   const global = readPendingAuthClaim(baseUrl, "global");
   return { claim: global, scope: global?.scope ?? "global" };
 }
@@ -15917,6 +15960,332 @@ import { homedir as homedir6, tmpdir as tmpdir5 } from "os";
 import { basename as basename4, dirname as dirname11, extname as extname3, join as join14, resolve as resolve13 } from "path";
 import { Option as Option2 } from "commander";
 
+// ../plays/settings-contract.ts
+import { z } from "zod";
+function formatPlaySettingsError(error) {
+  if (error instanceof z.ZodError)
+    return [...new Set(error.issues.map((issue) => issue.message))].join(" ");
+  return error instanceof Error ? error.message : String(error);
+}
+var PLAY_LOCATION_ROOTS = [
+  {
+    value: "person",
+    label: "Personal",
+    description: "The creator\u2019s personal root, displayed as their name followed by \u201C\u2019s team\u201D."
+  },
+  {
+    value: "team",
+    label: "Team library",
+    description: "The shared team library. Publishing moves personal locations here, keeping their folders."
+  }
+];
+var folder = z.string().min(1).max(128).refine(
+  (value) => value === value.trim() && value !== "." && value !== ".." && !/[\\/\u0000-\u001f\u007f]/u.test(value),
+  "Folder names must be trimmed, cannot be . or .., and cannot contain slashes or control characters."
+);
+var playPathSchema = z.union([
+  z.null(),
+  z.object({
+    root: z.enum(["person", "team"]),
+    folders: z.array(folder).max(16).default([])
+  }).strict()
+]).transform(
+  (path) => path?.root === "person" && path.folders.length === 0 ? null : path
+);
+function parsePlayPath(value) {
+  const [root, ...parts] = value.split("/");
+  if (!PLAY_LOCATION_ROOTS.some((option) => option.value === root)) {
+    throw new Error(
+      "Path must start with person or team. Example: person/Research/ICP."
+    );
+  }
+  let folders;
+  try {
+    folders = parts.map(decodeURIComponent);
+  } catch {
+    throw new Error(
+      "Path contains an invalid percent escape. Encode a literal % as %25."
+    );
+  }
+  return playPathSchema.parse({ root, folders });
+}
+function formatPlayPath(path) {
+  return path === null ? "person" : [path.root, ...path.folders.map(encodeURIComponent)].join("/");
+}
+function personalPlayRootLabel(ownerName) {
+  const name = ownerName?.trim();
+  return name ? `${name.split(/\s+/)[0]}\u2019s team` : "Personal";
+}
+function displayPlayPath(path, ownerName) {
+  return [
+    path?.root === "team" ? "Team library" : personalPlayRootLabel(ownerName),
+    ...path?.folders ?? []
+  ].join(" / ");
+}
+var PLAY_SETTING_FIELDS = {
+  path: {
+    schema: playPathSchema.default(null).describe(
+      "Play location. Null means the creator\u2019s personal root. Publishing moves it into Team library, preserving folders."
+    ),
+    label: "Location",
+    description: "Organize this Play in the creator\u2019s personal root or Team library. Publishing moves it to Team library and keeps its folders. Workspace sharing permissions apply in both roots.",
+    get defaultValue() {
+      return this.schema.parse(void 0);
+    },
+    cli: {
+      valueSyntax: "person[/folder/\u2026] | team[/folder/\u2026] | null",
+      examples: [
+        "person",
+        "person/Research/ICP",
+        "team",
+        "team/Research",
+        "null"
+      ],
+      parse: (value) => value === "null" ? null : parsePlayPath(value),
+      format: formatPlayPath
+    },
+    ui: { control: "play-location-picker" }
+  }
+};
+var playSettingsSchema = z.object(
+  Object.fromEntries(
+    Object.entries(PLAY_SETTING_FIELDS).map(([key, field]) => [
+      key,
+      field.schema
+    ])
+  )
+).passthrough();
+var playSettingsPatchSchema = z.object(
+  Object.fromEntries(
+    Object.entries(PLAY_SETTING_FIELDS).map(([key, field]) => [
+      key,
+      field.schema.unwrap().optional()
+    ])
+  )
+).strict().refine(
+  (patch) => Object.keys(patch).length > 0,
+  "Supply at least one setting."
+);
+function parsePlaySettings(value) {
+  return playSettingsSchema.parse(value);
+}
+var DEFAULT_PLAY_SETTINGS = parsePlaySettings({});
+
+// src/cli/commands/plays-settings.ts
+var fields = Object.entries(PLAY_SETTING_FIELDS);
+var help = `
+Settings live on the Play definition. Edits preserve code revisions.
+New Plays start at person (the creator\u2019s personal root, e.g. Chirag\u2019s team).
+Publishing moves a Play into team and keeps its folders. Workspace sharing
+permissions apply in both roots. Folder paths are independent of your cwd.
+
+Setting names and values:
+${fields.map(([key, field]) => `  ${key}: ${field.schema.description}
+    Values: ${field.cli.valueSyntax}
+    Default: ${JSON.stringify(field.defaultValue)} (${field.cli.format(field.defaultValue)})`).join("\n")}
+
+Roots:
+${PLAY_LOCATION_ROOTS.map((root) => `  ${root.value}: ${root.description}`).join("\n")}
+
+Examples:
+  deepline plays settings describe --name path --json
+  deepline plays settings get --play company-research --json
+  deepline plays settings get --play company-research --name path
+  deepline plays settings set --play company-research --name path --value person/Research/ICP
+  deepline plays settings set --play company-research --name path --value team/Research
+  deepline plays settings reset --play company-research --name path
+  deepline plays settings paths --root team --json
+
+Quote values containing spaces. Use percent escapes for literal % characters.
+`;
+function resolveField(key, command) {
+  const entry = fields.find(([name]) => name === key);
+  if (!entry)
+    command.error(
+      `Unknown --name ${JSON.stringify(key)}. Available settings: ${fields.map(([name]) => name).join(", ")}. Run deepline plays settings describe.`,
+      { exitCode: 2 }
+    );
+  return entry[1];
+}
+function printSettings(result, json2, name) {
+  const selected = fields.filter(([key]) => !name || key === name);
+  printCommandEnvelope(
+    {
+      ...result,
+      settings: Object.fromEntries(
+        selected.map(([key]) => [
+          key,
+          result.settings[key]
+        ])
+      ),
+      render: {
+        sections: [
+          {
+            title: "Play settings",
+            lines: selected.map(
+              ([key, field]) => `${field.label}: ${key === "path" ? displayPlayPath(result.settings.path, result.ownerName) : field.cli.format(result.settings[key])} (${field.cli.format(result.settings[key])})`
+            )
+          }
+        ]
+      }
+    },
+    { json: json2 }
+  );
+}
+function registerPlaySettingsCommands(plays) {
+  const settings = plays.command("settings").description("Read and change Play settings by name and value.").exitOverride((error) => {
+    if (error.exitCode !== 0) error.exitCode = 2;
+    throw error;
+  }).addHelpText("after", help);
+  settings.command("describe").usage("[--name <setting>] [options]").description(
+    "List setting names, values, examples and defaults; no authentication required."
+  ).option(
+    "--name <setting>",
+    `Describe one setting. Available: ${fields.map(([key]) => key).join(", ")}`
+  ).option("--json", "Emit JSON; automatic when piped").addHelpText("after", help).action((options, command) => {
+    if (options.name !== void 0) resolveField(options.name, command);
+    const descriptions = fields.filter(([name]) => !options.name || options.name === name).map(([name, field]) => ({
+      key: name,
+      label: field.label,
+      description: field.schema.description ?? field.description,
+      default: field.defaultValue,
+      defaultText: field.cli.format(field.defaultValue),
+      valueSyntax: field.cli.valueSyntax,
+      examples: field.cli.examples
+    }));
+    printCommandEnvelope(
+      {
+        fields: descriptions,
+        render: {
+          sections: descriptions.map((field) => ({
+            title: field.key,
+            lines: [
+              field.description,
+              `Values: ${field.valueSyntax}`,
+              `Default: ${JSON.stringify(field.default)} (${field.defaultText})`,
+              `Examples: ${field.examples.join(", ")}`
+            ]
+          }))
+        }
+      },
+      { json: options.json }
+    );
+  });
+  settings.command("get").usage("--play <play> [--name <setting>] [options]").description("Read all settings, or one setting selected with --name.").requiredOption("--play <play>", "Play to read").option(
+    "--name <setting>",
+    `Read one setting. Available: ${fields.map(([key]) => key).join(", ")}`
+  ).option("--json", "Emit JSON; automatic when piped").addHelpText("after", help).action(
+    async (options, command) => {
+      if (options.name !== void 0) resolveField(options.name, command);
+      printSettings(
+        await new DeeplineClient().getPlaySettings(options.play),
+        options.json,
+        options.name
+      );
+    }
+  );
+  const set = settings.command("set").usage("--play <play> --name <setting> --value <value> [options]").requiredOption("--play <play>", "Play to update").requiredOption(
+    "--name <setting>",
+    `Setting name. Available: ${fields.map(([key]) => key).join(", ")}`
+  ).requiredOption(
+    "--value <value>",
+    "New value; see settings describe --name <setting>"
+  ).description("Set one setting without creating or publishing a revision.");
+  const reset = settings.command("reset").usage("--play <play> --name <setting> [options]").requiredOption("--play <play>", "Play to update").requiredOption(
+    "--name <setting>",
+    `Setting name. Available: ${fields.map(([key]) => key).join(", ")}`
+  ).description("Reset one setting to its schema default.");
+  const change = async (command, play, key, value, options, resetting) => {
+    const field = resolveField(key, command);
+    let patch;
+    try {
+      patch = playSettingsPatchSchema.parse({
+        [key]: resetting ? field.defaultValue : field.cli.parse(value)
+      });
+    } catch (error) {
+      command.error(
+        `Invalid --value for --name ${key}: ${formatPlaySettingsError(error)} Values: ${field.cli.valueSyntax}.`,
+        { exitCode: 2 }
+      );
+    }
+    if (options.dryRun) {
+      printCommandEnvelope(
+        {
+          dryRun: true,
+          play,
+          patch,
+          render: {
+            sections: [
+              {
+                title: "Planned settings patch",
+                lines: Object.entries(patch).map(
+                  ([name, setting]) => `${name}: ${JSON.stringify(setting)}`
+                )
+              }
+            ]
+          }
+        },
+        { json: options.json }
+      );
+      return;
+    }
+    printSettings(
+      await new DeeplineClient().updatePlaySettings(play, patch),
+      options.json
+    );
+  };
+  for (const [command, resetting] of [
+    [set, false],
+    [reset, true]
+  ])
+    command.option("--dry-run", "Show the patch without changing settings").option("--json", "Emit JSON; automatic when piped").addHelpText("after", help).action(
+      (options) => change(
+        command,
+        options.play,
+        options.name,
+        options.value,
+        options,
+        resetting
+      )
+    );
+  settings.command("paths").description("List existing locations (one bounded page).").option("--root <person|team>", "Filter by root").option("--limit <n>", "Plays to inspect, 1\u2013100", "50").option("--cursor <cursor>", "Continue from a previous page").option("--json", "Emit JSON; automatic when piped").addHelpText("after", help).action(
+    async (options, command) => {
+      const limit = Number(options.limit);
+      if (options.root !== void 0 && options.root !== "person" && options.root !== "team" || !Number.isInteger(limit) || limit < 1 || limit > 100)
+        command.error(
+          "--root must be person or team; --limit must be 1\u2013100.",
+          { exitCode: 2 }
+        );
+      const page = await new DeeplineClient().listPlaySettingsPaths({
+        root: options.root,
+        limit,
+        cursor: options.cursor
+      });
+      const nextCommand = page.hasMore ? `deepline plays settings paths --cursor '${page.cursor}'${options.root ? ` --root ${options.root}` : ""} --json` : null;
+      printCommandEnvelope(
+        {
+          ...page,
+          nextCommand,
+          render: {
+            sections: [
+              {
+                title: "Play locations",
+                lines: [
+                  ...page.paths.map(
+                    (item) => `${displayPlayPath(item.path, item.ownerName)} (${formatPlayPath(item.path)}) \u2014 ${item.playName}`
+                  ),
+                  ...nextCommand ? [`More: ${nextCommand}`] : []
+                ]
+              }
+            ]
+          }
+        },
+        { json: options.json }
+      );
+    }
+  );
+}
+
 // src/cli/commands/play.ts
 import { createHash as createHash4, randomUUID as randomUUID4 } from "crypto";
 import {
@@ -16560,8 +16929,8 @@ function readCsvHeaderFields(csvPath, sample) {
     skip_empty_lines: false
   });
   const firstRecord = Array.isArray(records) ? records[0] : null;
-  const fields = Array.isArray(firstRecord) ? firstRecord.map((field) => String(field ?? "").trim()).filter(Boolean) : [];
-  const uniqueFields = [...new Set(fields)];
+  const fields2 = Array.isArray(firstRecord) ? firstRecord.map((field) => String(field ?? "").trim()).filter(Boolean) : [];
+  const uniqueFields = [...new Set(fields2)];
   if (uniqueFields.length === 0) {
     throw new PlayBootstrapUsageError(
       `Could not read a header row from --from csv:${csvPath}.`
@@ -17650,6 +18019,45 @@ Examples:
   });
 }
 
+// src/cli/commands/plays/run-history.ts
+async function handleRunsHistory(options) {
+  const query = new URLSearchParams();
+  if (options.cursor) query.set("cursor", options.cursor);
+  if (options.org) query.set("orgId", options.org);
+  if (options.limit !== void 0) {
+    const limit = Number(options.limit);
+    if (!/^\d+$/.test(options.limit) || !Number.isSafeInteger(limit) || limit < 1) {
+      throw new Error("--limit must be a positive integer.");
+    }
+    query.set("limit", String(limit));
+  }
+  const search = query.toString();
+  const page = await new HttpClient(resolveConfig()).get(
+    `/api/v2/dashboard/runs-history${search ? `?${search}` : ""}`
+  );
+  const lines = page.runs.map(
+    (run) => `${run.workflowName} \xB7 ${run.status} \xB7 ${run.runId}`
+  );
+  if (lines.length === 0) lines.push("No runs found on this page.");
+  if (page.hasMore) lines.push(`Next cursor: ${page.nextCursor}`);
+  printCommandEnvelope(
+    { ...page, render: { sections: [{ title: "Run history", lines }] } },
+    options.json ? { json: true } : {}
+  );
+}
+function registerRunHistoryCommand(runs) {
+  runs.command("history").description("Page workspace run history.").option(
+    "--cursor <cursor>",
+    "Opaque nextCursor returned by the previous page"
+  ).option("--limit <count>", "Maximum runs on this page").option(
+    "--org <id>",
+    "Workspace ID (must match the authenticated workspace)"
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").addHelpText(
+    "after",
+    "\nUse the opaque --cursor returned by the previous page to continue.\n\nExample:\n  deepline runs history --limit 100 --json\n"
+  ).action(handleRunsHistory);
+}
+
 // src/plays/bundle-play-file.ts
 import { tmpdir as tmpdir3 } from "os";
 import { dirname as dirname9, join as join9, resolve as resolve10 } from "path";
@@ -20554,7 +20962,7 @@ function recordCliTrace(event) {
   process.stderr.write(`[cli-trace] ${JSON.stringify(payload)}
 `);
 }
-async function traceCliSpan(phase, fields, run) {
+async function traceCliSpan(phase, fields2, run) {
   if (!isCliTraceEnabled()) {
     return run();
   }
@@ -20565,7 +20973,7 @@ async function traceCliSpan(phase, fields, run) {
       phase,
       ms: Date.now() - startedAt,
       ok: true,
-      ...fields
+      ...fields2
     });
     return result;
   } catch (error) {
@@ -20574,7 +20982,7 @@ async function traceCliSpan(phase, fields, run) {
       ms: Date.now() - startedAt,
       ok: false,
       error: error instanceof Error ? error.message : String(error),
-      ...fields
+      ...fields2
     });
     throw error;
   }
@@ -22418,6 +22826,7 @@ async function handlePlaysDeploy(directory, options) {
           },
           {
             bundle: bundleDeployPlayFile,
+            fetchImpl: fetchWithDeploymentProtection,
             // The plays are already here: "opening" the source is naming it.
             openSource: async () => ({
               open: async () => ({ repoRoot: root })
@@ -23129,7 +23538,7 @@ async function writePlayRunIdFile(destination, runId, options = {}) {
     await removeRunIdTempFile(tempPath);
   }
 }
-function traceCliSync(phase, fields, run) {
+function traceCliSync(phase, fields2, run) {
   const startedAt = Date.now();
   try {
     const result = run();
@@ -23137,7 +23546,7 @@ function traceCliSync(phase, fields, run) {
       phase,
       ms: Date.now() - startedAt,
       ok: true,
-      ...fields
+      ...fields2
     });
     return result;
   } catch (error) {
@@ -23146,7 +23555,7 @@ function traceCliSync(phase, fields, run) {
       ms: Date.now() - startedAt,
       ok: false,
       error: error instanceof Error ? error.message : String(error),
-      ...fields
+      ...fields2
     });
     throw error;
   }
@@ -24470,7 +24879,8 @@ function formatProgressCounts(input2) {
     Math.min(100, Math.round(completed / total * 100))
   );
   const failed = typeof input2.failed === "number" && Number.isFinite(input2.failed) && input2.failed > 0 ? `, failed ${formatInteger(input2.failed)}` : "";
-  return `${formatInteger(completed)}/${formatInteger(total)} (${percent}%)${failed}`;
+  const completedLabel = typeof input2.failed === "number" ? "successful " : "";
+  return `${completedLabel}${formatInteger(completed)}/${formatInteger(total)} (${percent}%)${failed}`;
 }
 function formatProgressMessageSuffix(input2) {
   const message = typeof input2.message === "string" ? input2.message.trim() : "";
@@ -25356,8 +25766,8 @@ function formatPlayLogLine(rawLine, status, state) {
     if (!logLevelReaches("info", state.logLevel ?? "info")) {
       return null;
     }
-    const [, rows, fields, namespace, cached, pending] = mapStart;
-    return `${prefix}map ${sourceLabelForNamespace(namespace)}: ${formatInteger(Number(rows))} rows, ${fields} fields, ${formatInteger(Number(cached))} cached, ${formatInteger(Number(pending))} pending`;
+    const [, rows, fields2, namespace, cached, pending] = mapStart;
+    return `${prefix}map ${sourceLabelForNamespace(namespace)}: ${formatInteger(Number(rows))} rows, ${fields2} fields, ${formatInteger(Number(cached))} cached, ${formatInteger(Number(pending))} pending`;
   }
   const mapDone = message.match(
     /^Map completed: (\d+) results \((\d+) executed, (\d+) already satisfied\)$/
@@ -26411,6 +26821,54 @@ function buildRunActivityTextLines(run) {
   if (observedAt) lines.push(`  observed: ${observedAt}`);
   return lines;
 }
+function formatObservedRunCounter(value) {
+  const counter = readRecord(value);
+  const count = counter?.value;
+  if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0) {
+    return "unknown";
+  }
+  return counter?.confirmed === true ? formatInteger(count) : `${formatInteger(count)} observed`;
+}
+function buildRunStatusEvidenceTextLines(packaged) {
+  const evidence = readRecord(packaged.runStatus);
+  if (!evidence || evidence.available !== true) return [];
+  const calls = readRecord(evidence.calls);
+  const lines = [];
+  if (calls) {
+    lines.push(
+      `  calls: ${formatObservedRunCounter(calls.logicalCalls)} logical, ${formatObservedRunCounter(calls.toolDispatches)} tool dispatches, ${formatObservedRunCounter(calls.provider429s)} provider 429s`
+    );
+  }
+  const source = readRecord(evidence.source);
+  if (source?.aligned === false) {
+    lines.push(
+      `  consistency: run snapshot event ${String(source.runSnapshotLedgerNextSeq)} and progress event ${String(source.ledgerNextSeq)} differ; retry this read to align them`
+    );
+  }
+  const focus = readRecord(evidence.focusStep);
+  const rows = readRecord(focus?.rows);
+  if (focus) {
+    const id = typeof focus.id === "string" && focus.id.trim() ? focus.id.trim() : "unknown step";
+    const label = typeof focus.label === "string" && focus.label.trim() ? ` (${focus.label.trim()})` : "";
+    const state = typeof focus.status === "string" && focus.status.trim() ? `: ${focus.status.trim()}` : "";
+    const rowCounts = rows ? `; rows ${formatObservedRunCounter({ value: rows.succeeded, confirmed: true })} succeeded, ${formatObservedRunCounter({ value: rows.failed, confirmed: true })} failed, ${formatObservedRunCounter({ value: rows.total, confirmed: true })} total` : "";
+    lines.push(`  current step: ${id}${label}${state}${rowCounts}`);
+  }
+  return lines;
+}
+function buildRecentRunLogTextLines(packaged) {
+  const logs = readRecord(packaged.logs);
+  const tail = Array.isArray(logs?.tail) ? logs.tail.filter((line) => typeof line === "string") : [];
+  if (tail.length === 0) return [];
+  const visible = tail.slice(-5);
+  const total = typeof logs?.totalCount === "number" && Number.isFinite(logs.totalCount) ? ` of ${formatInteger(logs.totalCount)}` : "";
+  const lines = [`  recent logs: showing ${visible.length}${total}`];
+  lines.push(...visible.map((line) => `    ${line}`));
+  if (logs?.truncated === true) {
+    lines.push("    older log lines were truncated by the retention cap");
+  }
+  return lines;
+}
 function buildRunPackageTextLines(packaged) {
   const run = readRunPackageRun(packaged);
   const runId = typeof run.id === "string" ? run.id : "unknown";
@@ -26480,6 +26938,8 @@ function buildRunPackageTextLines(packaged) {
   if (!isRuntimeLimitCheckpoint) {
     lines.push(...buildRunActivityTextLines(run));
   }
+  lines.push(...buildRunStatusEvidenceTextLines(packaged));
+  lines.push(...buildRecentRunLogTextLines(packaged));
   lines.push(...formatPackageValueOutputLines(packaged));
   lines.push(
     ...formatPackageDatasetActionLines(packaged, {
@@ -26487,12 +26947,7 @@ function buildRunPackageTextLines(packaged) {
     })
   );
   const next = packaged.next && typeof packaged.next === "object" && !Array.isArray(packaged.next) ? packaged.next : {};
-  const billingCommand = actionToCommand(next.billing);
   const logsCommand = actionToCommand(next.logs);
-  if (billingCommand) {
-    const costState = status === "completed" || status === "failed" || status === "cancelled" ? "settles asynchronously \u2014 run the billing command below for totals" : "pending";
-    lines.push(`  cost: ${costState}`);
-  }
   for (const step of isRuntimeLimitCheckpoint ? [] : readRecordArray(packaged.steps).slice(0, 8)) {
     const id = typeof step.id === "string" ? step.id : "step";
     const kind = typeof step.kind === "string" ? step.kind : "step";
@@ -26522,7 +26977,6 @@ function buildRunPackageTextLines(packaged) {
       `  ${isRuntimeTimeout ? "full run details" : "full result"}: ${fullResultCommand}`
     );
   if (logsCommand) lines.push(`  logs: ${logsCommand}`);
-  if (billingCommand) lines.push(`  billing: ${billingCommand}`);
   if (legacyExportCommand) {
     lines.push(`  export CSV: ${legacyExportCommand}`);
   }
@@ -30117,8 +30571,8 @@ function printPlayDescription(play) {
   }
 }
 function inputFieldNames(schema) {
-  const fields = Array.isArray(schema?.fields) ? schema.fields : [];
-  return fields.map(
+  const fields2 = Array.isArray(schema?.fields) ? schema.fields : [];
+  return fields2.map(
     (field) => field && typeof field === "object" ? String(field.name ?? "").trim() : ""
   ).filter(Boolean);
 }
@@ -30135,9 +30589,9 @@ function printCompactPlaySearchResult(play) {
   if (aliases) {
     console.log(`  Aliases: ${aliases}`);
   }
-  const fields = inputFieldNames(play.inputSchema);
-  if (fields.length > 0) {
-    console.log(`  Inputs: ${fields.join(", ")}`);
+  const fields2 = inputFieldNames(play.inputSchema);
+  if (fields2.length > 0) {
+    console.log(`  Inputs: ${fields2.join(", ")}`);
   } else if (play.inputSchema) {
     console.log("  Inputs: see describe");
   }
@@ -30146,14 +30600,14 @@ function printCompactPlaySearchResult(play) {
 }
 function compactPlaySchema(schema) {
   if (!schema) return null;
-  const fields = Array.isArray(schema.fields) ? schema.fields.map(
+  const fields2 = Array.isArray(schema.fields) ? schema.fields.map(
     (field) => field && typeof field === "object" ? {
       name: String(field.name ?? ""),
       type: field.type ?? void 0,
       required: field.required ?? void 0
     } : null
   ).filter((field) => Boolean(field?.name)) : [];
-  return fields.length > 0 ? { fields } : schema;
+  return fields2.length > 0 ? { fields: fields2 } : schema;
 }
 function summarizePlayGrepResult(play) {
   const reference = formatPlayListReference(play);
@@ -30782,6 +31236,8 @@ Concepts:
   Installed npm and repo-local CLIs can run saved/prebuilt plays by name or
   bundle local .play.ts files for development workflows.
   Running a local file does not make it live; use publish or set-live for that.
+  plays settings organizes a Play independently of code revisions.
+  New Plays start at person; publishing moves them to team, preserving folders.
 
 Authoring:
   Use normal TypeScript interpolation for human-facing strings:
@@ -30987,6 +31443,7 @@ Pass-through input flags:
     process.exitCode = exitCode;
   });
   registerPlayBootstrapCommand(play);
+  registerPlaySettingsCommands(play);
   play.command("get <target>").description(
     "Fetch full play details or materialize a saved source bundle."
   ).addHelpText(
@@ -31255,6 +31712,8 @@ Notes:
   plays check to refuse publishing bytes that changed after validation.
   --dry-run bundles only and prints the exact artifact that would be published.
   Running a local file with plays run does not publish it.
+  Publishing moves personal locations into Team library, preserving folders.
+  Change location with: deepline plays settings set --play <play> --name path --value team/Research
 
 Examples:
   deepline plays set-live my-play --latest --json
@@ -31398,7 +31857,10 @@ Examples:
   deepline runs export play/my-play/run/20260501t000000-000 --out output.csv
 `
   );
-  runs.command("status <runId>").description("Read bounded lifecycle and confirmed work counts for a run.").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
+  registerRunHistoryCommand(runs);
+  runs.command("status <runId>").description(
+    "Legacy scalar-only read. Use runs get for canonical status, progress, logs, and results."
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunLifecycleStatus([
       runId,
       ...options.json ? ["--json"] : []
@@ -35004,9 +35466,9 @@ function readEnrichRunStatus(status) {
   return null;
 }
 function firstCollectedStringField(value, key) {
-  const fields = /* @__PURE__ */ new Set();
-  collectStringFields(value, key, fields);
-  return fields.values().next().value ?? null;
+  const fields2 = /* @__PURE__ */ new Set();
+  collectStringFields(value, key, fields2);
+  return fields2.values().next().value ?? null;
 }
 function emitPlainRunFailure(status) {
   const runId = extractRunId(status) ?? firstCollectedStringField(status, "runId");
@@ -47803,7 +48265,7 @@ function requireCatalogEvent(settings, eventType) {
   }
   return event;
 }
-async function printSettings(options) {
+async function printSettings2(options) {
   const settings = await new DeeplineClient().getNotificationSettings();
   const slack = slackDestination(settings);
   const destinationId = typeof slack?._id === "string" ? slack._id : void 0;
@@ -47930,7 +48392,7 @@ Slack is the delivery integration. This command group only manages product
 notifications; there is no general integrations CLI.
 `
   );
-  notifications.command("get").description("Show destination, subscriptions, and DLQ health.").option("--json", "Emit JSON output").action(printSettings);
+  notifications.command("get").description("Show destination, subscriptions, and DLQ health.").option("--json", "Emit JSON output").action(printSettings2);
   notifications.command("connect").description("Start the OAuth connection required by a destination.").argument("<destination>", "Destination kind (currently slack)").option("--open", "Open the Slack authorization URL in a browser").option("--dry-run", "Describe the mutation without starting OAuth").option("--json", "Emit JSON output").action(
     async (destination, options) => {
       if (destination !== "slack")
@@ -49368,6 +49830,8 @@ async function searchTools(queryInput, options = {}) {
     query,
     categories: options.categories,
     searchTerms: options.searchTerms,
+    limit: options.limit,
+    offset: options.offset,
     searchMode: options.searchMode,
     includeSearchDebug: options.includeSearchDebug
   });
@@ -49598,13 +50062,15 @@ Notes:
   that can be passed to deepline tools describe or deepline tools execute.
   Provide a query, or omit it only when --categories and/or --search_terms is
   supplied. Providing neither is a usage error. Both filters accept
-  comma-separated values. Use a provider name in the query; --prefix is not a
-  supported option.
+  comma-separated values. Use --limit and --offset to page through ranked
+  results (limit 1-50, offset is zero-based); JSON includes next_offset.
+  Use a provider name in the query; --prefix is not a supported option.
   The grep alias is the same ranked retrieval surface with a more literal name
   for agents that are filtering a registry rather than choosing a workflow.
 
 Examples:
-  deepline tools search email
+  deepline tools search email --limit 10 --json
+  deepline tools search email --limit 10 --offset 10 --json
   deepline tools search --categories company_search --search_terms "investors,funding"
   deepline tools grep "company enrichment" --categories enrichment --json
   deepline tools search verifier --search-mode v2 --json
@@ -49615,10 +50081,12 @@ Examples:
   ).option(
     "--search_terms <terms>",
     "Comma-separated structured search terms; may be used without a query"
-  ).option("--search-terms <terms>", "Alias for --search_terms").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
+  ).option("--search-terms <terms>", "Alias for --search_terms").option("--limit <count>", "Maximum ranked results to return (1-50)").option("--offset <count>", "Zero-based ranked result offset").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
     process.exitCode = await searchTools(query, {
       json: options.json,
       compact: options.compact,
+      limit: options.limit !== void 0 ? Number.parseInt(options.limit, 10) : void 0,
+      offset: options.offset !== void 0 ? Number.parseInt(options.offset, 10) : void 0,
       categories: options.categories,
       searchTerms: options.searchTerms ?? options.search_terms,
       searchMode: options.searchMode === "v1" || options.searchMode === "v2" ? options.searchMode : void 0,
@@ -50021,8 +50489,8 @@ function printMonitorTypeFilters(tool) {
 }
 function printMonitorTypeFilterExamples(tool) {
   const documentation = recordField2(tool, "documentation");
-  const fields = recordField2(documentation, "fields");
-  const examples = Object.entries(fields).flatMap(([name, rawField]) => {
+  const fields2 = recordField2(documentation, "fields");
+  const examples = Object.entries(fields2).flatMap(([name, rawField]) => {
     const grammar = recordField2(isRecord12(rawField) ? rawField : {}, "grammar");
     const example = stringField2(grammar, "example");
     const values = [
@@ -50377,9 +50845,9 @@ function sampleValueForField(field) {
   if (type === "object") return {};
   return "...";
 }
-function samplePayloadForInputFields(fields) {
+function samplePayloadForInputFields(fields2) {
   return Object.fromEntries(
-    fields.slice(0, 4).flatMap((field) => {
+    fields2.slice(0, 4).flatMap((field) => {
       if (!isRecord12(field)) return [];
       const name = stringField2(field, "name");
       if (!name) return [];
@@ -50510,8 +50978,8 @@ function formatListedToolCost(tool) {
 }
 function toolInputFieldsForDisplay(inputSchema) {
   if (Array.isArray(inputSchema.fields)) {
-    const fields = inputSchema.fields.filter(isRecord12);
-    if (!isRecord12(inputSchema.jsonSchema)) return fields;
+    const fields2 = inputSchema.fields.filter(isRecord12);
+    if (!isRecord12(inputSchema.jsonSchema)) return fields2;
     const jsonSchemaFields = new Map(
       recursiveToolInputFieldsForDisplay({
         jsonSchema: inputSchema.jsonSchema
@@ -50519,7 +50987,7 @@ function toolInputFieldsForDisplay(inputSchema) {
         (field) => typeof field.name === "string" ? [[field.name, field]] : []
       )
     );
-    return fields.map((field) => {
+    return fields2.map((field) => {
       const jsonSchemaField = typeof field.name === "string" ? jsonSchemaFields.get(field.name) : void 0;
       const minItems = typeof field.minItems === "number" ? field.minItems : jsonSchemaField?.minItems;
       const maxItems = typeof field.maxItems === "number" ? field.maxItems : jsonSchemaField?.maxItems;
@@ -50616,7 +51084,7 @@ function publicToolInputSchemaForDescribe(inputSchema) {
 }
 function recursiveToolInputFieldsForDisplay(inputSchema) {
   const root = canonicalToolJsonSchema(inputSchema);
-  const fields = /* @__PURE__ */ new Map();
+  const fields2 = /* @__PURE__ */ new Map();
   const schemasById = /* @__PURE__ */ new Map();
   const collectSchemaIds = (value) => {
     if (Array.isArray(value)) {
@@ -50644,9 +51112,9 @@ function recursiveToolInputFieldsForDisplay(inputSchema) {
   const addField = (field) => {
     const name = typeof field.name === "string" ? field.name : "";
     if (!name) return;
-    const existing = fields.get(name);
+    const existing = fields2.get(name);
     if (!existing || existing.type === "unknown") {
-      fields.set(name, field);
+      fields2.set(name, field);
     }
   };
   const visit = (unresolvedSchema, path, required, activeRefs = /* @__PURE__ */ new Set()) => {
@@ -50694,7 +51162,7 @@ function recursiveToolInputFieldsForDisplay(inputSchema) {
     }
   };
   visit(root, "", false);
-  return fields.size ? [...fields.values()] : toolInputFieldsForDisplay(inputSchema);
+  return fields2.size ? [...fields2.values()] : toolInputFieldsForDisplay(inputSchema);
 }
 function inputFieldJsonForDescribe(field) {
   const publicItems = isRecord12(field.items) ? publicToolInputSchemaForDescribe({ items: field.items }).items : void 0;