deepline 0.1.12 → 0.1.20

package/dist/repo/sdk/src/cli/commands/play.ts

@@ -1,3441 +0,0 @@
-import { createHash } from 'node:crypto';
-import {
-  existsSync,
-  readFileSync,
-  readdirSync,
-  realpathSync,
-  writeFileSync,
-} from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
-import { Command, Option } from 'commander';
-import { DeeplineClient, type PlayStatus } from '../../client.js';
-import { DeeplineError } from '../../errors.js';
-import {
-  bundlePlayFile,
-  extractDefinedPlayName,
-  type BundledPlayFileSuccess,
-} from '../../plays/bundle-play-file.js';
-import type { PlayStagedFileRef } from '../../plays/local-file-discovery.js';
-import type {
-  PlayDescription,
-  PlayDetail,
-  PlayLiveEvent,
-  PlayListItem,
-  PlayRevisionSummary,
-  PlayRunListItem,
-} from '../../types.js';
-import {
-  buildDatasetStats,
-  extractCanonicalRowsInfo,
-  writeCanonicalRowsCsv,
-  type CanonicalRowsInfo,
-  type DatasetStats,
-} from '../dataset-stats.js';
-import {
-  createCliProgress,
-  getActiveCliProgress,
-  type CliProgress,
-} from '../progress.js';
-import { argsWantJson } from '../utils.js';
-
-type PlayRunCommandOptions = {
-  target: { kind: 'file'; path: string } | { kind: 'name'; name: string };
-  input: Record<string, unknown> | null;
-  revisionId: string | null;
-  revisionSelector: 'live' | 'latest' | null;
-  watch: boolean;
-  emitLogs: boolean;
-  jsonOutput: boolean;
-  pollIntervalMs: number;
-  waitTimeoutMs: number | null;
-  force: boolean;
-  outPath: string | null;
-};
-
-type FileInputBinding = {
-  inputPath: string;
-};
-
-type PlayCheckCommandOptions = {
-  target: string;
-  jsonOutput: boolean;
-};
-
-type PlaySearchOptions = {
-  query: string;
-  jsonOutput: boolean;
-  compact: boolean;
-  origin: 'prebuilt' | 'owned' | undefined;
-};
-
-function parseReferencedPlayTarget(target: string): {
-  ownerSlug: string | null;
-  playName: string;
-  unqualifiedPlayName: string;
-} {
-  const trimmed = target.trim();
-  const slashIndex = trimmed.indexOf('/');
-  if (slashIndex <= 0 || slashIndex === trimmed.length - 1) {
-    return { ownerSlug: null, playName: trimmed, unqualifiedPlayName: trimmed };
-  }
-  return {
-    ownerSlug: trimmed.slice(0, slashIndex),
-    playName: trimmed,
-    unqualifiedPlayName: trimmed.slice(slashIndex + 1),
-  };
-}
-
-function isPrebuiltReferenceTarget(target: string): boolean {
-  return target.trim().toLowerCase().startsWith('prebuilt/');
-}
-
-function buildBarePrebuiltReferenceError(input: {
-  requested: string;
-  reference: string;
-}): Error {
-  return new Error(
-    `Prebuilt play "${input.requested}" must be referenced as "${input.reference}". ` +
-      `Use the prebuilt/ namespace anywhere you run, describe, get, or link to Deepline-managed plays.`,
-  );
-}
-
-async function assertCanonicalNamedPlayReference(
-  client: DeeplineClient,
-  target: string,
-): Promise<PlayDetail> {
-  const parsed = parseReferencedPlayTarget(target);
-  const detail = await client.getPlay(parsed.playName);
-  if (
-    detail.play.ownerType === 'deepline' &&
-    !isPrebuiltReferenceTarget(target)
-  ) {
-    throw buildBarePrebuiltReferenceError({
-      requested: target,
-      reference: formatPlayReference(detail.play),
-    });
-  }
-  return detail;
-}
-
-function formatPlayReference(
-  play: Pick<PlayDetail['play'], 'reference' | 'ownerSlug' | 'name'>,
-): string {
-  if (play.reference) {
-    return play.reference;
-  }
-  const ownerSlug = play.ownerSlug?.trim() || 'org';
-  return `${ownerSlug}/${play.name}`;
-}
-
-function formatPlayListReference(play: PlayListItem | PlayDescription): string {
-  return play.reference || play.name;
-}
-
-function defaultMaterializedPlayPath(reference: string): string {
-  const playName = parseReferencedPlayTarget(reference).unqualifiedPlayName;
-  const safeName = playName
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9-]/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-|-$/g, '');
-  return resolve(`${safeName || 'play'}.play.ts`);
-}
-
-type MaterializedRemotePlaySource = {
-  path: string;
-  status: 'created' | 'updated' | 'unchanged';
-  created: boolean;
-};
-
-function materializeRemotePlaySource(input: {
-  target: string;
-  playName: string;
-  sourceCode: string;
-  outPath: string | null;
-}): MaterializedRemotePlaySource | null {
-  if (isFileTarget(input.target)) {
-    return null;
-  }
-  if (!input.sourceCode.trim()) {
-    return null;
-  }
-
-  const outputPath =
-    input.outPath ?? defaultMaterializedPlayPath(input.playName);
-  if (existsSync(outputPath)) {
-    const existingSource = readFileSync(outputPath, 'utf-8');
-    if (existingSource === input.sourceCode) {
-      return { path: outputPath, status: 'unchanged', created: false };
-    }
-    writeFileSync(outputPath, input.sourceCode, 'utf-8');
-    return { path: outputPath, status: 'updated', created: false };
-  }
-
-  writeFileSync(outputPath, input.sourceCode, 'utf-8');
-  return { path: outputPath, status: 'created', created: true };
-}
-
-function formatLoadedPlayMessage(
-  materializedFile: MaterializedRemotePlaySource,
-): string {
-  if (materializedFile.status === 'unchanged') {
-    return `Loaded play here: ${materializedFile.path} (unchanged)`;
-  }
-  if (materializedFile.status === 'updated') {
-    return `Loaded play here: ${materializedFile.path} (updated)`;
-  }
-  return `Loaded play here: ${materializedFile.path}`;
-}
-
-function buildReadonlyPrebuiltPlayError(reference: string): Error {
-  return new Error(
-    `Cannot edit or push ${reference} because Deepline prebuilt plays are read-only.\n` +
-      `To make your own version:\n` +
-      `1. Copy the source into a new local file.\n` +
-      `2. Change definePlay('${reference.split('/').slice(1).join('/')}', ...) to a new play name you own.\n` +
-      `3. Run: deepline plays publish <your-file.play.ts>\n` +
-      `4. Your play will then live under your workspace namespace.`,
-  );
-}
-
-async function ensureEditableRemotePlay(
-  client: DeeplineClient,
-  target: string,
-): Promise<PlayDetail> {
-  const parsed = parseReferencedPlayTarget(target);
-  const detail = await client.getPlay(parsed.playName);
-  if (detail.play.ownerType === 'deepline') {
-    throw buildReadonlyPrebuiltPlayError(formatPlayReference(detail.play));
-  }
-  return detail;
-}
-
-function buildMissingDefinePlayError(filePath: string): Error {
-  return new Error(
-    `Play file ${filePath} must export definePlay('play-name', async (...) => { ... }). ` +
-      'Plain `export default async function ...` plays are no longer supported for SDK/CLI file-backed runs.',
-  );
-}
-
-function extractPlayName(code: string, filePath: string): string {
-  const definedPlayName = extractDefinedPlayName(code, filePath);
-  if (definedPlayName) {
-    return definedPlayName;
-  }
-  throw buildMissingDefinePlayError(filePath);
-}
-
-function isFileTarget(target: string): boolean {
-  return existsSync(resolve(target));
-}
-
-function looksLikeFilePath(target: string): boolean {
-  if (target.trim().toLowerCase().startsWith('prebuilt/')) {
-    return false;
-  }
-  if (
-    target.startsWith('./') ||
-    target.startsWith('../') ||
-    target.startsWith('/') ||
-    target.startsWith('~/')
-  ) {
-    return true;
-  }
-  return (
-    target.includes('\\') ||
-    /\.(ts|js|mjs|play\.ts)$/.test(target)
-  );
-}
-
-function parsePositiveInteger(value: string, flagName: string): number {
-  const parsed = Number.parseInt(value, 10);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new Error(`${flagName} must be a positive integer.`);
-  }
-  return parsed;
-}
-
-function parseJsonInput(raw: string): Record<string, unknown> {
-  const source = raw.startsWith('@')
-    ? readFileSync(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.');
-  }
-  return parsed as Record<string, unknown>;
-}
-
-function parseInputFieldFlag(
-  rawFlag: string,
-  nextArg: string | undefined,
-): { path: string; value: string } {
-  const flag = rawFlag.slice(2);
-  const equalsIndex = flag.indexOf('=');
-  if (equalsIndex > 0) {
-    const path = flag.slice(0, equalsIndex).trim();
-    const value = flag.slice(equalsIndex + 1);
-    if (!path) {
-      throw new Error(`Invalid play input flag: ${rawFlag}`);
-    }
-    return { path, value };
-  }
-  if (!nextArg || nextArg.startsWith('--')) {
-    throw new Error(`Play input flag ${rawFlag} requires a value.`);
-  }
-  return { path: flag, value: nextArg };
-}
-
-function parseInputFlagValue(raw: string): unknown {
-  const trimmed = raw.trim();
-  if (!trimmed) return '';
-  if (
-    trimmed === 'true' ||
-    trimmed === 'false' ||
-    trimmed === 'null' ||
-    trimmed.startsWith('{') ||
-    trimmed.startsWith('[') ||
-    /^-?\d+(\.\d+)?$/.test(trimmed)
-  ) {
-    try {
-      return JSON.parse(trimmed);
-    } catch {
-      return raw;
-    }
-  }
-  return raw;
-}
-
-function getDottedInputValue(
-  input: Record<string, unknown>,
-  path: string,
-): unknown {
-  const parts = path.split('.').map((part) => part.trim()).filter(Boolean);
-  let cursor: unknown = input;
-  for (const part of parts) {
-    if (!cursor || typeof cursor !== 'object' || Array.isArray(cursor)) {
-      return undefined;
-    }
-    cursor = (cursor as Record<string, unknown>)[part];
-  }
-  return cursor;
-}
-
-function setDottedInputValue(
-  input: Record<string, unknown>,
-  path: string,
-  value: unknown,
-): void {
-  const parts = path.split('.').map((part) => part.trim()).filter(Boolean);
-  if (parts.length === 0) {
-    throw new Error(`Invalid play input flag path: ${path}`);
-  }
-  let cursor: Record<string, unknown> = input;
-  for (const part of parts.slice(0, -1)) {
-    const existing = cursor[part];
-    if (
-      existing !== undefined &&
-      (!existing || typeof existing !== 'object' || Array.isArray(existing))
-    ) {
-      throw new Error(
-        `Cannot set --${path}; input.${part} is already a non-object value.`,
-      );
-    }
-    if (!existing) {
-      cursor[part] = {};
-    }
-    cursor = cursor[part] as Record<string, unknown>;
-  }
-  cursor[parts[parts.length - 1]!] = value;
-}
-
-function schemaMetadata(
-  schema: Record<string, unknown> | null | undefined,
-  key: string,
-): Record<string, unknown> | null {
-  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return null;
-  const value = schema[key];
-  return value && typeof value === 'object' && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : null;
-}
-
-function stringMetadata(
-  metadata: Record<string, unknown> | null | undefined,
-  key: string,
-): string | null {
-  const value = metadata?.[key];
-  return typeof value === 'string' && value.trim() ? value.trim() : null;
-}
-
-function inputFieldFromCsvArg(csvArg: unknown): string | null {
-  if (typeof csvArg !== 'string') return null;
-  const match = /^input\.([A-Za-z_$][\w$]*)$/.exec(csvArg.trim());
-  return match?.[1] ?? null;
-}
-
-function fileInputBindingsFromPlaySchema(
-  inputSchema: Record<string, unknown> | null | undefined,
-): FileInputBinding[] {
-  const csvInput = schemaMetadata(inputSchema, 'csvInput');
-  if (!csvInput) return [];
-  return [
-    {
-      inputPath: stringMetadata(csvInput, 'inputField') ?? 'csv',
-    },
-  ];
-}
-
-function fileInputBindingsFromStaticPipeline(
-  staticPipeline: unknown,
-): FileInputBinding[] {
-  if (!staticPipeline || typeof staticPipeline !== 'object' || Array.isArray(staticPipeline)) {
-    return [];
-  }
-  const inputField = inputFieldFromCsvArg(
-    (staticPipeline as Record<string, unknown>).csvArg,
-  );
-  return inputField ? [{ inputPath: inputField }] : [];
-}
-
-function isLocalFilePathValue(value: unknown): value is string {
-  if (typeof value !== 'string' || !value.trim()) return false;
-  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value.trim())) return false;
-  return existsSync(resolve(value));
-}
-
-async function stageFileInputArgs(input: {
-  client: DeeplineClient;
-  runtimeInput: Record<string, unknown>;
-  bindings: FileInputBinding[];
-  progress: CliProgress;
-}): Promise<{
-  inputFile: PlayStagedFileRef | null;
-  packagedFiles: PlayStagedFileRef[];
-}> {
-  const uniqueBindings = [
-    ...new Map(input.bindings.map((binding) => [binding.inputPath, binding])).values(),
-  ];
-  const localFiles = uniqueBindings.flatMap((binding) => {
-    const value = getDottedInputValue(input.runtimeInput, binding.inputPath);
-    if (!isLocalFilePathValue(value)) return [];
-    const absolutePath = resolve(value);
-    return [{ binding, absolutePath, logicalPath: basename(absolutePath) }];
-  });
-
-  if (localFiles.length === 0) {
-    return { inputFile: null, packagedFiles: [] };
-  }
-
-  input.progress.phase(
-    localFiles.length === 1 ? 'staging input file' : 'staging input files',
-  );
-  const staged = await input.client.stagePlayFiles(
-    localFiles.map((file) => stageFile(file.logicalPath, file.absolutePath)),
-  );
-  for (const [index, file] of localFiles.entries()) {
-    setDottedInputValue(input.runtimeInput, file.binding.inputPath, file.logicalPath);
-    const stagedFile = staged[index];
-    if (stagedFile && stagedFile.logicalPath !== file.logicalPath) {
-      setDottedInputValue(input.runtimeInput, file.binding.inputPath, stagedFile.logicalPath);
-    }
-  }
-
-  return {
-    inputFile: staged[0] ?? null,
-    packagedFiles: staged.slice(1),
-  };
-}
-
-function stageFile(logicalPath: string, absolutePath: string) {
-  const buffer = readFileSync(absolutePath);
-  return {
-    logicalPath,
-    contentBase64: buffer.toString('base64'),
-    contentHash: createHash('sha256').update(buffer).digest('hex'),
-    contentType: absolutePath.toLowerCase().endsWith('.csv')
-      ? 'text/csv'
-      : absolutePath.toLowerCase().endsWith('.json')
-        ? 'application/json'
-        : 'application/octet-stream',
-    bytes: buffer.byteLength,
-  };
-}
-
-function normalizePlayPath(filePath: string): string {
-  try {
-    return realpathSync.native(resolve(filePath));
-  } catch {
-    return resolve(filePath);
-  }
-}
-
-function formatBundlingErrors(filePath: string, errors: string[]): string {
-  return `Failed to bundle ${filePath}: ${errors.join('; ')}`;
-}
-
-function formatUnresolvedPackagedFiles(
-  filePath: string,
-  unresolvedFileReferences: BundledPlayFileSuccess['unresolvedFileReferences'],
-): string {
-  const details = unresolvedFileReferences
-    .map((unresolved) => `${unresolved.sourceFragment}: ${unresolved.message}`)
-    .join('; ');
-  return `Failed to package local ctx.csv(...) files in ${filePath}: ${details}`;
-}
-
-async function collectBundledPlayGraph(entryFile: string): Promise<{
-  root: BundledPlayFileSuccess;
-  nodes: Map<string, BundledPlayFileSuccess>;
-}> {
-  const nodes = new Map<string, BundledPlayFileSuccess>();
-  const visiting = new Set<string>();
-
-  const visit = async (filePath: string): Promise<BundledPlayFileSuccess> => {
-    const absolutePath = normalizePlayPath(filePath);
-    const cached = nodes.get(absolutePath);
-    if (cached) {
-      return cached;
-    }
-    if (visiting.has(absolutePath)) {
-      throw new Error(
-        `Recursive imported play graph detected while bundling ${absolutePath}. ` +
-          'Break the import cycle and compose plays with ctx.runPlay(...) instead.',
-      );
-    }
-
-    visiting.add(absolutePath);
-    try {
-      // Bundle target is hardcoded to esm_workers — workers_edge is the
-      // server-side default execution profile and the only deployable
-      // runtime. The legacy cjs_node20 target remains in the bundler for
-      // benchmarks that pass `--profile legacy`, but the CLI does not
-      // auto-select it.
-      const bundleResult = await bundlePlayFile(absolutePath, {
-        target: 'esm_workers',
-      });
-      if (bundleResult.success === false) {
-        throw new Error(
-          formatBundlingErrors(absolutePath, bundleResult.errors),
-        );
-      }
-      if (bundleResult.unresolvedFileReferences.length > 0) {
-        throw new Error(
-          formatUnresolvedPackagedFiles(
-            absolutePath,
-            bundleResult.unresolvedFileReferences,
-          ),
-        );
-      }
-
-      nodes.set(absolutePath, bundleResult);
-      for (const dependency of bundleResult.importedPlayDependencies) {
-        await visit(dependency.filePath);
-      }
-      return bundleResult;
-    } finally {
-      visiting.delete(absolutePath);
-    }
-  };
-
-  const root = await visit(entryFile);
-  return { root, nodes };
-}
-
-async function compileBundledPlayGraphManifests(
-  client: DeeplineClient,
-  graph: {
-    root: BundledPlayFileSuccess;
-    nodes: Map<string, BundledPlayFileSuccess>;
-  },
-): Promise<void> {
-  const compiling = new Map<string, Promise<void>>();
-  const compileNode = (node: BundledPlayFileSuccess): Promise<void> => {
-    const existing = compiling.get(node.filePath);
-    if (existing) return existing;
-
-    const promise = (async () => {
-      for (const dependency of node.importedPlayDependencies) {
-        const child = graph.nodes.get(normalizePlayPath(dependency.filePath));
-        if (!child) {
-          throw new Error(
-            `Missing bundled play graph node for imported dependency ${dependency.filePath}.`,
-          );
-        }
-        await compileNode(child);
-      }
-
-      const name =
-        node.playName ?? extractPlayName(node.sourceCode, node.filePath);
-      node.compilerManifest = await client.compilePlayManifest({
-        name,
-        sourceCode: node.sourceCode,
-        artifact: node.artifact,
-        importedPlayDependencies: node.importedPlayDependencies.map(
-          (dependency) => {
-            const child = graph.nodes.get(
-              normalizePlayPath(dependency.filePath),
-            );
-            if (!child?.compilerManifest) {
-              throw new Error(
-                `Missing compiler manifest for imported dependency ${dependency.filePath}.`,
-              );
-            }
-            return child.compilerManifest;
-          },
-        ),
-      });
-    })();
-
-    compiling.set(node.filePath, promise);
-    return promise;
-  };
-
-  await compileNode(graph.root);
-}
-
-function requireCompilerManifest(node: BundledPlayFileSuccess) {
-  if (!node.compilerManifest) {
-    throw new Error(`Missing compiler manifest for ${node.filePath}.`);
-  }
-  return node.compilerManifest;
-}
-
-async function publishImportedPlayDependencies(
-  client: DeeplineClient,
-  graph: {
-    root: BundledPlayFileSuccess;
-    nodes: Map<string, BundledPlayFileSuccess>;
-  },
-): Promise<void> {
-  const published = new Set<string>();
-
-  const publishNode = async (
-    filePath: string,
-    skipPublish: boolean,
-  ): Promise<void> => {
-    const absolutePath = normalizePlayPath(filePath);
-    const node = graph.nodes.get(absolutePath);
-    if (!node) {
-      throw new Error(`Missing bundled play graph node for ${absolutePath}.`);
-    }
-
-    for (const dependency of node.importedPlayDependencies) {
-      await publishNode(dependency.filePath, false);
-    }
-
-    if (skipPublish || published.has(absolutePath)) {
-      return;
-    }
-
-    if (!node.playName) {
-      throw new Error(
-        `Imported play ${absolutePath} must export definePlay(...) so it can be published for runtime composition.`,
-      );
-    }
-
-    await client.registerPlayArtifact({
-      name: node.playName,
-      sourceCode: node.sourceCode,
-      artifact: node.artifact,
-      compilerManifest: requireCompilerManifest(node),
-      publish: true,
-    });
-    published.add(absolutePath);
-  };
-
-  await publishNode(graph.root.filePath, true);
-}
-
-function formatTimestamp(value: string | number | null | undefined): string {
-  if (!value) return '—';
-  const date = typeof value === 'number' ? new Date(value) : new Date(value);
-  if (Number.isNaN(date.getTime())) return '—';
-  return date.toISOString();
-}
-
-function formatRunLine(run: PlayRunListItem): string {
-  return `${run.workflowId} ${run.status} ${formatTimestamp(run.startTime)}`;
-}
-
-type PlayRunTarget =
-  | { kind: 'run'; runId: string }
-  | { kind: 'name'; name: string };
-
-function parsePlayRunTarget(input: {
-  args: string[];
-  usage: string;
-  allowName: boolean;
-}): PlayRunTarget {
-  const { args, usage } = input;
-  let runId: string | null = null;
-  let playName: string | null = null;
-
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index]!;
-    if (arg === '--json') {
-      continue;
-    }
-    if (
-      arg === '--reason' ||
-      arg === '--interval-ms' ||
-      arg === '--poll-interval-ms'
-    ) {
-      index += 1;
-      continue;
-    }
-    if (arg === '--run-id' && args[index + 1]) {
-      runId = args[++index]!.trim();
-      continue;
-    }
-    if (arg === '--name' && args[index + 1] && input.allowName) {
-      playName = parseReferencedPlayTarget(args[++index]!).playName;
-      continue;
-    }
-    if (arg.startsWith('--')) {
-      continue;
-    }
-    throw new DeeplineError(
-      `Unexpected positional target "${arg}". Use --run-id for run ids.\n${usage}`,
-    );
-  }
-
-  const explicitTargets = [runId, playName].filter(Boolean).length;
-  if (explicitTargets > 1) {
-    throw new DeeplineError(`Choose exactly one play run target.\n${usage}`);
-  }
-
-  if (runId) {
-    return { kind: 'run', runId };
-  }
-  if (playName) {
-    return { kind: 'name', name: playName };
-  }
-  throw new DeeplineError(usage);
-}
-
-async function resolvePlayRunId(
-  client: DeeplineClient,
-  target: PlayRunTarget,
-): Promise<string> {
-  if (target.kind === 'run') {
-    try {
-      const status = await client.getPlayStatus(target.runId);
-      return status.runId;
-    } catch (error) {
-      if (!(error instanceof DeeplineError) || error.statusCode !== 404) {
-        throw error;
-      }
-      throw new DeeplineError(`No play run found for run id: ${target.runId}`);
-    }
-  }
-
-  const runs = await client.listPlayRuns(target.name);
-  const workflowId = runs[0]?.workflowId ?? '';
-  if (!workflowId) {
-    throw new DeeplineError(`No runs found for play: ${target.name}`);
-  }
-  return workflowId;
-}
-
-function isTransientPlayStatusPollError(error: unknown): boolean {
-  if (error instanceof DeeplineError && typeof error.statusCode === 'number') {
-    // Server-shaped errors with a definite status code are NOT transient by
-    // pattern — only network-level failures are. 5xx counts as transient
-    // since the server may recover, but 4xx (especially 404 = run gone) is
-    // terminal and should not be hidden behind a silent retry loop.
-    return error.statusCode >= 500 && error.statusCode < 600;
-  }
-  const text = error instanceof Error ? error.message : String(error);
-  return /auth validation backend timed out|fetch failed|eaddrnotavail|econnreset|etimedout|eai_again|socket hang up/i.test(
-    text,
-  );
-}
-
-function isTerminalPlayStatusPollError(input: {
-  error: unknown;
-  hasSeenRun: boolean;
-}): boolean {
-  // A 404 *after* we've already seen the run means the run was deleted or
-  // the backend lost it — never recover, fail loud. A 404 *before* we've
-  // seen the run is the persistence race (submit accepted but the Convex
-  // record hasn't been written yet); treat that as transient.
-  if (
-    input.error instanceof DeeplineError &&
-    input.error.statusCode === 404 &&
-    input.hasSeenRun
-  ) {
-    return true;
-  }
-  return false;
-}
-
-const TERMINAL_PLAY_STATUSES = new Set<PlayStatus['status']>([
-  'completed',
-  'failed',
-  'cancelled',
-]);
-
-type PlayTailPrintState = {
-  lastLogIndex: number;
-  emittedRunnerStarted: boolean;
-};
-
-function getEventPayload(event: PlayLiveEvent): Record<string, unknown> {
-  return event.payload && typeof event.payload === 'object'
-    ? (event.payload as Record<string, unknown>)
-    : {};
-}
-
-function getStatusFromLiveEvent(
-  event: PlayLiveEvent,
-): PlayStatus['status'] | null {
-  if (event.type !== 'play.run.status' && event.type !== 'play.run.snapshot') {
-    return null;
-  }
-  const status = getEventPayload(event).status;
-  return status === 'queued' ||
-    status === 'running' ||
-    status === 'waiting' ||
-    status === 'completed' ||
-    status === 'failed' ||
-    status === 'cancelled'
-    ? status
-    : null;
-}
-
-function getFinalStatusFromLiveEvent(event: PlayLiveEvent): PlayStatus | null {
-  if (event.type !== 'play.run.final_status') {
-    return null;
-  }
-  const payload = getEventPayload(event);
-  const status = payload.status;
-  if (status !== 'completed' && status !== 'failed' && status !== 'cancelled') {
-    return null;
-  }
-  return {
-    ...(payload as unknown as Omit<PlayStatus, 'runId' | 'status'>),
-    runId: typeof payload.runId === 'string' ? payload.runId : '',
-    status,
-  };
-}
-
-function getLogLinesFromLiveEvent(event: PlayLiveEvent): string[] {
-  if (event.type !== 'play.run.log') {
-    return [];
-  }
-  const lines = getEventPayload(event).lines;
-  return Array.isArray(lines)
-    ? lines.filter((line): line is string => typeof line === 'string')
-    : [];
-}
-
-function describeLiveEventPhase(event: PlayLiveEvent): string | null {
-  const payload = getEventPayload(event);
-  if (event.type === 'play.run.status') {
-    const status = getStatusFromLiveEvent(event);
-    if (status === 'running') {
-      return null;
-    }
-    const runId =
-      typeof payload.runId === 'string' && payload.runId
-        ? ` ${payload.runId}`
-        : '';
-    return status ? `${status}${runId}` : null;
-  }
-  if (
-    event.type === 'play.step.status' ||
-    event.type === 'play.step.progress'
-  ) {
-    const label =
-      typeof payload.label === 'string' && payload.label.trim()
-        ? payload.label.trim()
-        : typeof payload.stepId === 'string' && payload.stepId.trim()
-          ? payload.stepId.trim()
-          : 'step';
-    const completed =
-      typeof payload.completed === 'number' ? payload.completed : null;
-    const total = typeof payload.total === 'number' ? payload.total : null;
-    const progress =
-      completed !== null && total !== null ? ` ${completed}/${total}` : '';
-    return `step ${label}${progress}`;
-  }
-  if (
-    event.type === 'play.sheet.summary' ||
-    event.type === 'play.sheet.delta'
-  ) {
-    const table =
-      typeof payload.tableNamespace === 'string' ? payload.tableNamespace : '';
-    return table ? `updating table ${table}` : 'updating table';
-  }
-  return null;
-}
-
-function buildPlayDashboardUrl(baseUrl: string, playName: string): string {
-  const trimmedBase = baseUrl.replace(/\/$/, '');
-  const encodedPlayName = encodeURIComponent(playName);
-  return `${trimmedBase}/dashboard/plays/${encodedPlayName}`;
-}
-
-function getDashboardUrlFromLiveEvent(event: PlayLiveEvent): string | null {
-  const dashboardUrl = getEventPayload(event).dashboardUrl;
-  return typeof dashboardUrl === 'string' && dashboardUrl.trim()
-    ? dashboardUrl.trim()
-    : null;
-}
-
-function printPlayLogLines(input: {
-  lines: string[];
-  status: PlayStatus | null;
-  jsonOutput: boolean;
-  emitLogs: boolean;
-  state: PlayTailPrintState;
-  progress: CliProgress;
-}) {
-  for (const line of input.lines) {
-    if (input.emitLogs) {
-      const formatted = formatPlayLogLine(
-        line,
-        input.status ?? undefined,
-        input.state,
-      );
-      if (formatted) {
-        input.progress.writeLogLine(formatted);
-      }
-    }
-    input.state.lastLogIndex += 1;
-  }
-}
-
-function assertPlayWaitNotTimedOut(input: {
-  workflowId: string;
-  startedAt: number;
-  waitTimeoutMs: number | null;
-  lastPhase?: string | null;
-}) {
-  if (
-    input.waitTimeoutMs !== null &&
-    Date.now() - input.startedAt >= input.waitTimeoutMs
-  ) {
-    const hasRealRunId =
-      input.workflowId.length > 0 && input.workflowId !== 'pending';
-    const phaseSuffix =
-      input.lastPhase && input.lastPhase.trim()
-        ? ` (last observed phase: ${input.lastPhase.trim()})`
-        : '';
-    const tailHint = hasRealRunId
-      ? ` Run 'deepline play tail --run-id ${input.workflowId} --json' to inspect it, or rerun with a larger --tail-timeout-ms.`
-      : ` The run never reported a workflow id — the start request likely failed before reaching the scheduler. Check server logs and rerun with a larger --tail-timeout-ms.`;
-    throw new DeeplineError(
-      `Timed out waiting for play ${hasRealRunId ? input.workflowId : '<no run id>'} after ${Math.ceil(input.waitTimeoutMs / 1000)}s${phaseSuffix}.${tailHint}`,
-      undefined,
-      'PLAY_WAIT_TIMEOUT',
-      {
-        ...(hasRealRunId
-          ? { runId: input.workflowId, workflowId: input.workflowId }
-          : {}),
-        ...(input.lastPhase ? { phase: input.lastPhase } : {}),
-        timeoutMs: input.waitTimeoutMs,
-      },
-    );
-  }
-}
-
-async function waitForPlayCompletionByStream(input: {
-  client: DeeplineClient;
-  workflowId: string;
-  jsonOutput: boolean;
-  emitLogs: boolean;
-  waitTimeoutMs: number | null;
-  startedAt: number;
-  state: PlayTailPrintState;
-  progress: CliProgress;
-}): Promise<PlayStatus> {
-  const controller = new AbortController();
-  let timedOut = false;
-  let lastPhase: string | null = null;
-  const timeout =
-    input.waitTimeoutMs === null
-      ? null
-      : setTimeout(
-          () => {
-            timedOut = true;
-            controller.abort();
-          },
-          Math.max(1, input.waitTimeoutMs - (Date.now() - input.startedAt)),
-        );
-
-  try {
-    for await (const event of input.client.streamPlayRunEvents(
-      input.workflowId,
-      { signal: controller.signal },
-    )) {
-      assertPlayWaitNotTimedOut({ ...input, lastPhase });
-      const phase = describeLiveEventPhase(event);
-      if (phase) {
-        lastPhase = phase;
-        input.progress.phase(phase);
-      }
-      printPlayLogLines({
-        lines: getLogLinesFromLiveEvent(event),
-        status: null,
-        jsonOutput: input.jsonOutput,
-        emitLogs: input.emitLogs,
-        state: input.state,
-        progress: input.progress,
-      });
-
-      const status = getStatusFromLiveEvent(event);
-      if (status && TERMINAL_PLAY_STATUSES.has(status)) {
-        const finalStatus = await input.client.getPlayStatus(input.workflowId);
-        if (TERMINAL_PLAY_STATUSES.has(finalStatus.status)) {
-          return finalStatus;
-        }
-      }
-    }
-  } catch (error) {
-    if (timedOut) {
-      assertPlayWaitNotTimedOut({ ...input, lastPhase });
-    }
-    throw error;
-  } finally {
-    if (timeout) {
-      clearTimeout(timeout);
-    }
-  }
-
-  const phaseSuffix =
-    lastPhase && lastPhase.trim()
-      ? ` (last observed phase: ${lastPhase.trim()})`
-      : '';
-  throw new DeeplineError(
-    `Play live stream ended before the run reached a terminal state runId=${input.workflowId}${phaseSuffix}.`,
-    undefined,
-    'PLAY_LIVE_STREAM_ENDED',
-    {
-      runId: input.workflowId,
-      workflowId: input.workflowId,
-      ...(lastPhase ? { phase: lastPhase } : {}),
-    },
-  );
-}
-
-async function startAndWaitForPlayCompletionByStream(input: {
-  client: DeeplineClient;
-  request: Parameters<DeeplineClient['startPlayRun']>[0];
-  playName: string;
-  jsonOutput: boolean;
-  emitLogs: boolean;
-  waitTimeoutMs: number | null;
-  progress: CliProgress;
-}): Promise<PlayStatus> {
-  const startedAt = Date.now();
-  const state: PlayTailPrintState = {
-    lastLogIndex: 0,
-    emittedRunnerStarted: false,
-  };
-  const controller = new AbortController();
-  let timedOut = false;
-  let emittedDashboardUrl = false;
-  let lastKnownWorkflowId = '';
-  let lastPhase: string | null = null;
-  const timeout =
-    input.waitTimeoutMs === null
-      ? null
-      : setTimeout(
-          () => {
-            timedOut = true;
-            controller.abort();
-          },
-          Math.max(1, input.waitTimeoutMs),
-        );
-
-  try {
-    for await (const event of input.client.startPlayRunStream(input.request, {
-      signal: controller.signal,
-    })) {
-      const eventRunId = getEventPayload(event).runId;
-      if (
-        typeof eventRunId === 'string' &&
-        eventRunId &&
-        eventRunId !== 'pending'
-      ) {
-        lastKnownWorkflowId = eventRunId;
-      }
-      const workflowId = lastKnownWorkflowId || 'pending';
-      if (workflowId !== 'pending' && !emittedDashboardUrl) {
-        const dashboardUrl =
-          getDashboardUrlFromLiveEvent(event) ??
-          buildPlayDashboardUrl(input.client.baseUrl, input.playName);
-        if (!input.jsonOutput) {
-          writeStartedPlayRun({
-            runId: workflowId,
-            playName: input.playName,
-            dashboardUrl,
-            jsonOutput: false,
-            progress: input.progress,
-          });
-        }
-        input.progress.phase(`loading play on ${dashboardUrl}`);
-        emittedDashboardUrl = true;
-      }
-      assertPlayWaitNotTimedOut({
-        workflowId,
-        startedAt,
-        waitTimeoutMs: input.waitTimeoutMs,
-        lastPhase,
-      });
-      const phase = describeLiveEventPhase(event);
-      if (phase) {
-        lastPhase = phase;
-        input.progress.phase(phase);
-      }
-      printPlayLogLines({
-        lines: getLogLinesFromLiveEvent(event),
-        status: null,
-        jsonOutput: input.jsonOutput,
-        emitLogs: input.emitLogs,
-        state,
-        progress: input.progress,
-      });
-
-      const finalStatus = getFinalStatusFromLiveEvent(event);
-      if (finalStatus) {
-        return finalStatus;
-      }
-    }
-  } catch (error) {
-    if (timedOut) {
-      assertPlayWaitNotTimedOut({
-        workflowId: lastKnownWorkflowId,
-        startedAt,
-        waitTimeoutMs: input.waitTimeoutMs,
-        lastPhase,
-      });
-    }
-    if (lastKnownWorkflowId && isTransientPlayStatusPollError(error)) {
-      if (timeout) {
-        clearTimeout(timeout);
-      }
-      const reason = error instanceof Error ? error.message : String(error);
-      process.stderr.write(
-        `[play watch] start stream failed after run ${lastKnownWorkflowId}; falling back to polling (${reason})\n`,
-      );
-      return waitForPlayCompletionByPolling({
-        client: input.client,
-        workflowId: lastKnownWorkflowId,
-        pollIntervalMs: 500,
-        jsonOutput: input.jsonOutput,
-        emitLogs: input.emitLogs,
-        waitTimeoutMs: input.waitTimeoutMs,
-        startedAt,
-        state,
-        progress: input.progress,
-      });
-    }
-    throw error;
-  } finally {
-    if (timeout) {
-      clearTimeout(timeout);
-    }
-  }
-
-  const phaseSuffix =
-    lastPhase && lastPhase.trim()
-      ? ` (last observed phase: ${lastPhase.trim()})`
-      : '';
-  const idSuffix = lastKnownWorkflowId ? ` runId=${lastKnownWorkflowId}` : '';
-  throw new DeeplineError(
-    `Play start stream ended before the run reached a terminal state${idSuffix}${phaseSuffix}.`,
-    undefined,
-    'PLAY_START_STREAM_ENDED',
-    {
-      ...(lastKnownWorkflowId
-        ? { runId: lastKnownWorkflowId, workflowId: lastKnownWorkflowId }
-        : {}),
-      ...(lastPhase ? { phase: lastPhase } : {}),
-    },
-  );
-}
-
-async function waitForPlayCompletionByPolling(input: {
-  client: DeeplineClient;
-  workflowId: string;
-  pollIntervalMs: number;
-  jsonOutput: boolean;
-  emitLogs: boolean;
-  waitTimeoutMs: number | null;
-  startedAt: number;
-  state: PlayTailPrintState;
-  progress: CliProgress;
-}): Promise<PlayStatus> {
-  let lastTransientPollWarningAt = 0;
-  let hasSeenRun = false;
-
-  while (true) {
-    assertPlayWaitNotTimedOut(input);
-
-    let status: PlayStatus;
-    try {
-      status = await input.client.getPlayTailStatus(input.workflowId, {
-        afterLogIndex: input.state.lastLogIndex,
-        // Keep the server-side tail wait close to the caller's requested poll
-        // cadence. A long wait makes tiny remote runs look slow whenever the
-        // terminal update lands just after the held request starts.
-        waitMs: Math.max(50, Math.min(input.pollIntervalMs, 1_000)),
-      });
-    } catch (error) {
-      if (isTerminalPlayStatusPollError({ error, hasSeenRun })) {
-        throw new DeeplineError(
-          `Play run ${input.workflowId} no longer exists on the server (404). The run was deleted or the backend lost it.`,
-          404,
-          'PLAY_RUN_NOT_FOUND',
-        );
-      }
-      if (!isTransientPlayStatusPollError(error)) {
-        throw error;
-      }
-      const now = Date.now();
-      if (now - lastTransientPollWarningAt >= 30_000) {
-        const message = error instanceof Error ? error.message : String(error);
-        input.progress.writeLine(
-          `[play tail] transient status poll failed; retrying: ${message}`,
-        );
-        lastTransientPollWarningAt = now;
-      }
-      await new Promise((resolvePromise) =>
-        setTimeout(resolvePromise, input.pollIntervalMs),
-      );
-      continue;
-    }
-    hasSeenRun = true;
-    const logs = status.progress?.logs ?? [];
-    input.progress.phase(status.status);
-    printPlayLogLines({
-      lines: logs.slice(input.state.lastLogIndex),
-      status,
-      jsonOutput: input.jsonOutput,
-      emitLogs: input.emitLogs,
-      state: input.state,
-      progress: input.progress,
-    });
-
-    if (TERMINAL_PLAY_STATUSES.has(status.status)) {
-      return status.result !== undefined
-        ? status
-        : await input.client.getPlayStatus(input.workflowId);
-    }
-
-    const authoritativeStatus = await input.client.getPlayStatus(
-      input.workflowId,
-    );
-    if (TERMINAL_PLAY_STATUSES.has(authoritativeStatus.status)) {
-      return authoritativeStatus;
-    }
-
-    if ((status.progress?.logs ?? []).length === input.state.lastLogIndex) {
-      await new Promise((resolvePromise) =>
-        setTimeout(resolvePromise, input.pollIntervalMs),
-      );
-    }
-  }
-}
-
-async function waitForPlayCompletion(input: {
-  client: DeeplineClient;
-  workflowId: string;
-  pollIntervalMs: number;
-  jsonOutput: boolean;
-  emitLogs: boolean;
-  waitTimeoutMs: number | null;
-  progress: CliProgress;
-}): Promise<PlayStatus> {
-  const startedAt = Date.now();
-  const state: PlayTailPrintState = {
-    lastLogIndex: 0,
-    emittedRunnerStarted: false,
-  };
-  try {
-    return await waitForPlayCompletionByStream({
-      ...input,
-      startedAt,
-      state,
-      progress: input.progress,
-    });
-  } catch (error) {
-    assertPlayWaitNotTimedOut({
-      workflowId: input.workflowId,
-      startedAt,
-      waitTimeoutMs: input.waitTimeoutMs,
-    });
-    // Loud one-line note so the user can tell SSE failed and we are now
-    // polling. Repeated SSE failures should be diagnosed, not hidden.
-    const reason = error instanceof Error ? error.message : String(error);
-    process.stderr.write(
-      `[play watch] SSE stream failed; falling back to polling (${reason})\n`,
-    );
-    return waitForPlayCompletionByPolling({
-      ...input,
-      startedAt,
-      state,
-      progress: input.progress,
-    });
-  }
-}
-
-function formatInteger(value: unknown): string {
-  return typeof value === 'number' && Number.isFinite(value)
-    ? value.toLocaleString('en-US')
-    : String(value ?? '-');
-}
-
-function formatPercent(numerator: number, denominator: number): string {
-  if (denominator <= 0) {
-    return '-';
-  }
-  const percent = (numerator / denominator) * 100;
-  return `${percent.toFixed(percent >= 10 ? 0 : 1)}%`;
-}
-
-function isFilledValue(value: unknown): boolean {
-  if (value === null || value === undefined) {
-    return false;
-  }
-  if (typeof value === 'string') {
-    return value.trim().length > 0;
-  }
-  if (Array.isArray(value)) {
-    return value.length > 0;
-  }
-  if (typeof value === 'object') {
-    return Object.keys(value).length > 0;
-  }
-  return true;
-}
-
-const BULKY_RETURN_KEYS = new Set([
-  'contract',
-  'staticPipeline',
-  'batchingTrace',
-  'sequenceTrace',
-  'logs',
-]);
-
-function formatPlayLogLine(
-  line: string,
-  status: PlayStatus | undefined,
-  state: PlayTailPrintState,
-): string | null {
-  const timestampMatch = line.match(/^\[([^\]]+)\]\s*(.*)$/);
-  const parsedTimestamp = timestampMatch?.[1]
-    ? new Date(timestampMatch[1])
-    : null;
-  const timestamp =
-    parsedTimestamp && !Number.isNaN(parsedTimestamp.getTime())
-      ? parsedTimestamp.toLocaleTimeString('en-US', {
-          hour12: false,
-          hour: '2-digit',
-          minute: '2-digit',
-          second: '2-digit',
-        })
-      : null;
-  const message = timestampMatch?.[2] ?? line;
-  const prefix = timestamp ? `${timestamp} ` : '';
-
-  if (/\[worker\] picked up run\b/.test(message)) {
-    if (state.emittedRunnerStarted) {
-      return null;
-    }
-    state.emittedRunnerStarted = true;
-    return `${prefix}runner started`;
-  }
-
-  if (
-    /\[worker\] step started\b/.test(message) ||
-    /\[worker\] Preparing run files\b/.test(message) ||
-    /\[worker\] Run files ready\b/.test(message) ||
-    /\[worker\] Runtime ready\b/.test(message) ||
-    /\[worker\] Sandbox (?:starting|create start|create done|workspace ready|upload start|runner uploaded)\b/.test(
-      message,
-    )
-  ) {
-    return null;
-  }
-
-  const stages = (
-    (
-      status?.contract as
-        | {
-            staticPipeline?: {
-              stages?: Array<{
-                tableNamespace?: string;
-                sourceRange?: { startLine?: number; endLine?: number };
-              }>;
-            };
-          }
-        | null
-        | undefined
-    )?.staticPipeline?.stages ?? []
-  ).filter((stage) => stage.tableNamespace);
-  const sourceLabelForNamespace = (namespace: string): string => {
-    const stage = stages.find((entry) => entry.tableNamespace === namespace);
-    const range = stage?.sourceRange;
-    return range?.startLine && range?.endLine
-      ? `${namespace} lines ${range.startLine}-${range.endLine}`
-      : namespace;
-  };
-
-  const mapStart = message.match(
-    /^Starting map over (\d+) items with (\d+) fields \(key: ([^;]+); (\d+) already satisfied; (\d+) pending\)$/,
-  );
-  if (mapStart) {
-    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 mapDone = message.match(
-    /^Map completed: (\d+) results \((\d+) executed, (\d+) already satisfied\)$/,
-  );
-  if (mapDone) {
-    const [, results, executed, cached] = mapDone;
-    return `${prefix}done: ${formatInteger(Number(results))} results, ${formatInteger(Number(executed))} executed, ${formatInteger(Number(cached))} cached`;
-  }
-
-  return `${prefix}${message}`;
-}
-
-function compactReturnValue(value: unknown, depth = 0): unknown {
-  if (depth >= 4) {
-    return value && typeof value === 'object' ? '[Object]' : value;
-  }
-  if (Array.isArray(value)) {
-    const compacted = value
-      .slice(0, 5)
-      .map((entry) => compactReturnValue(entry, depth + 1));
-    return value.length > 5
-      ? [...compacted, `... ${value.length - 5} more`]
-      : compacted;
-  }
-  if (!value || typeof value !== 'object') {
-    return value;
-  }
-
-  const output: Record<string, unknown> = {};
-  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
-    if (depth === 0 && key === '_metadata') {
-      continue;
-    }
-    if (BULKY_RETURN_KEYS.has(key)) {
-      continue;
-    }
-    if (key === 'access') {
-      continue;
-    }
-    output[key] = compactReturnValue(entry, depth + 1);
-  }
-  return output;
-}
-
-function extractResultRowsInfo(result: Record<string, unknown>): {
-  rows: unknown[];
-  totalRows: number | null;
-  sampled: boolean;
-} {
-  const output = result.output as Record<string, unknown> | undefined;
-  const candidate =
-    (output?.results as unknown[] | undefined) ??
-    (output?.rows as unknown[] | undefined) ??
-    (result.results as unknown[] | undefined) ??
-    (result.rows as unknown[] | undefined) ??
-    (result.previewRows as unknown[] | undefined);
-  if (Array.isArray(candidate)) {
-    return { rows: candidate, totalRows: candidate.length, sampled: false };
-  }
-
-  const dataset =
-    (result.rows &&
-    typeof result.rows === 'object' &&
-    !Array.isArray(result.rows)
-      ? (result.rows as Record<string, unknown>)
-      : null) ??
-    (output?.rows &&
-    typeof output.rows === 'object' &&
-    !Array.isArray(output.rows)
-      ? (output.rows as Record<string, unknown>)
-      : null);
-  if (dataset && Array.isArray(dataset.preview)) {
-    return {
-      rows: dataset.preview,
-      totalRows:
-        typeof dataset.count === 'number' && Number.isFinite(dataset.count)
-          ? dataset.count
-          : dataset.preview.length,
-      sampled: true,
-    };
-  }
-
-  return { rows: [], totalRows: null, sampled: false };
-}
-
-function formatJsonPreview(value: unknown): string[] {
-  const json = JSON.stringify(value, null, 2);
-  if (!json || json === '{}') {
-    return [];
-  }
-
-  const MAX_CHARS = 4_000;
-  const truncated =
-    json.length > MAX_CHARS
-      ? `${json.slice(0, MAX_CHARS)}\n... truncated; use --json for full output`
-      : json;
-  return truncated.split('\n').map((line) => `    ${line}`);
-}
-
-function formatReturnValue(result: Record<string, unknown>): string[] {
-  const previewLines = formatJsonPreview(compactReturnValue(result));
-  if (previewLines.length === 0) {
-    return [];
-  }
-  const lines = ['  return value:'];
-  lines.push(...previewLines);
-  const hiddenKeys = [...BULKY_RETURN_KEYS].filter(
-    (key) => result[key] !== undefined,
-  );
-  if (hiddenKeys.length > 0) {
-    lines.push(`    omitted metadata from preview: ${hiddenKeys.join(', ')}`);
-  }
-  return lines;
-}
-
-function formatTableSummary(result: Record<string, unknown>): string[] {
-  const { rows, totalRows, sampled } = extractResultRowsInfo(result);
-  const recordRows = rows.filter(
-    (row): row is Record<string, unknown> =>
-      Boolean(row) && typeof row === 'object' && !Array.isArray(row),
-  );
-  if (recordRows.length === 0) {
-    return [];
-  }
-
-  const columns = [...new Set(recordRows.flatMap((row) => Object.keys(row)))];
-  const displayedRows = recordRows.length;
-  const denominator =
-    sampled && totalRows !== null ? displayedRows : recordRows.length;
-  const lines = [
-    `    rows=${formatInteger(totalRows ?? recordRows.length)}  columns=${formatInteger(columns.length)}${sampled ? `  previewRows=${formatInteger(displayedRows)}` : ''}`,
-  ];
-  const fillStats = columns
-    .filter((column) => !column.startsWith('_'))
-    .map((column) => {
-      const filled = recordRows.filter((row) =>
-        isFilledValue(row[column]),
-      ).length;
-      return { column, filled };
-    })
-    .sort((a, b) => b.filled - a.filled)
-    .slice(0, 8);
-  if (fillStats.length > 0) {
-    lines.push(
-      `    fill rates: ${fillStats
-        .map(
-          (stat) =>
-            `${stat.column}=${formatInteger(stat.filled)}/${formatInteger(denominator)} (${formatPercent(stat.filled, denominator)})${sampled ? ' sample' : ''}`,
-        )
-        .join(', ')}`,
-    );
-  }
-  return lines;
-}
-
-function buildOutputSummary(
-  rowsInfo: CanonicalRowsInfo | null,
-  exportedPath?: string | null,
-): Record<string, unknown> | null {
-  if (!rowsInfo) {
-    return exportedPath ? { csv_path: exportedPath } : null;
-  }
-  return {
-    kind: 'rows',
-    rowCount: rowsInfo.totalRows,
-    previewRowCount: rowsInfo.rows.length,
-    complete: rowsInfo.complete,
-    columns: rowsInfo.columns,
-    source: rowsInfo.source,
-    ...(exportedPath ? { csv_path: exportedPath } : {}),
-  };
-}
-
-function buildRunWarnings(
-  status: PlayStatus,
-  rowsInfo: CanonicalRowsInfo | null,
-): string[] {
-  if (status.status === 'completed' && rowsInfo?.totalRows === 0) {
-    return ['Run completed with 0 output rows.'];
-  }
-  return [];
-}
-
-function buildRunNextCommands(runId: string): Record<string, string> {
-  return {
-    exportCsv: `deepline runs export ${runId} --out output.csv`,
-    status: `deepline runs status ${runId} --json`,
-    logs: `deepline runs logs ${runId}`,
-  };
-}
-
-function isTerminalPlayStatus(status: PlayStatus): boolean {
-  return TERMINAL_PLAY_STATUSES.has(status.status);
-}
-
-function compactPlayStatus(
-  status: PlayStatus,
-  options?: { exportedPath?: string | null },
-): Record<string, unknown> {
-  const rowsInfo = extractCanonicalRowsInfo(status);
-  const result =
-    status && typeof status === 'object'
-      ? (status as unknown as { result?: unknown }).result
-      : null;
-  const warnings = buildRunWarnings(status, rowsInfo);
-  const datasetStats =
-    rowsInfo && rowsInfo.complete
-      ? buildDatasetStats(rowsInfo.rows, rowsInfo.totalRows, rowsInfo.columns)
-      : null;
-  const billing =
-    status && typeof status === 'object'
-      ? (status as unknown as { billing?: unknown }).billing
-      : null;
-  const progressError = (
-    status.progress as unknown as Record<string, unknown> | undefined
-  )?.error;
-  const error =
-    typeof progressError === 'string'
-      ? progressError
-      : typeof (status as unknown as { error?: unknown }).error === 'string'
-        ? String((status as unknown as { error?: unknown }).error)
-        : null;
-  return {
-    runId: status.runId,
-    apiVersion: status.apiVersion ?? 1,
-    ...(typeof (status as unknown as { name?: unknown }).name === 'string'
-      ? { name: (status as unknown as { name: string }).name }
-      : {}),
-    ...(typeof (status as unknown as { playName?: unknown }).playName ===
-    'string'
-      ? { playName: (status as unknown as { playName: string }).playName }
-      : {}),
-    status: status.status,
-    ...(error ? { error } : {}),
-    ...(warnings.length > 0 ? { warnings } : {}),
-    output:
-      buildOutputSummary(rowsInfo, options?.exportedPath) ?? result ?? null,
-    ...(result !== undefined ? { result } : {}),
-    ...(status.resultView ? { resultView: status.resultView } : {}),
-    ...(datasetStats ? { dataset_stats: datasetStats } : {}),
-    ...(rowsInfo ? { previewRows: rowsInfo.rows.slice(0, 5) } : {}),
-    ...(billing ? { billing } : {}),
-    ...(status.run ? { run: status.run } : {}),
-    next: buildRunNextCommands(status.runId),
-  };
-}
-
-function enrichPlayStatusWithDatasetStats(
-  status: PlayStatus,
-): PlayStatus & { dataset_stats?: DatasetStats } {
-  const rowsInfo = extractCanonicalRowsInfo(status);
-  if (!rowsInfo?.complete) {
-    return status;
-  }
-  return {
-    ...status,
-    dataset_stats: buildDatasetStats(
-      rowsInfo.rows,
-      rowsInfo.totalRows,
-      rowsInfo.columns,
-    ),
-  };
-}
-
-function formatDatasetStatsLines(datasetStats: DatasetStats | null): string[] {
-  if (!datasetStats) {
-    return [];
-  }
-  const lines = ['  column stats:'];
-  for (const [column, stat] of Object.entries(datasetStats.columnStats).slice(
-    0,
-    12,
-  )) {
-    const topValues = stat.top_values
-      ? `, top_values=${Object.entries(stat.top_values)
-          .slice(0, 3)
-          .map(([value, count]) => `${value}=${count}`)
-          .join(', ')}`
-      : '';
-    const sample =
-      stat.sample_value !== undefined
-        ? `, sample_value=${JSON.stringify(stat.sample_value)}`
-        : '';
-    lines.push(
-      `    ${column}: non_empty=${stat.non_empty}, unique=${stat.unique}${topValues}${sample}`,
-    );
-  }
-  return lines;
-}
-
-function writePlayResult(
-  status: PlayStatus,
-  jsonOutput: boolean,
-  options?: { exportedPath?: string | null; fullJson?: boolean },
-): void {
-  if (jsonOutput) {
-    process.stdout.write(
-      `${JSON.stringify(
-        options?.fullJson
-          ? enrichPlayStatusWithDatasetStats(status)
-          : compactPlayStatus(status, options),
-      )}\n`,
-    );
-    return;
-  }
-
-  const result = status.result as Record<string, unknown> | undefined;
-  const publicStatus = status.status ?? 'running';
-  const success = publicStatus === 'completed';
-  const runId = status.runId ?? 'unknown';
-
-  const lines: string[] = [];
-  lines.push(`${success ? '✓' : '✗'} ${publicStatus}  ${runId}`);
-  const rowsInfo = extractCanonicalRowsInfo(status);
-  const warnings = buildRunWarnings(status, rowsInfo);
-  const datasetStats =
-    rowsInfo && rowsInfo.complete
-      ? buildDatasetStats(rowsInfo.rows, rowsInfo.totalRows, rowsInfo.columns)
-      : null;
-  const outputSummary = buildOutputSummary(rowsInfo, options?.exportedPath);
-  if (outputSummary) {
-    const columns = Array.isArray(outputSummary.columns)
-      ? outputSummary.columns.length
-      : 0;
-    const path =
-      typeof outputSummary.csv_path === 'string'
-        ? `  file=${outputSummary.csv_path}`
-        : '';
-    lines.push(
-      `  output: rows=${formatInteger(outputSummary.rowCount)}  columns=${formatInteger(columns)}${path}`,
-    );
-  }
-  for (const warning of warnings) {
-    lines.push(`  warning: ${warning}`);
-  }
-  lines.push(...formatDatasetStatsLines(datasetStats));
-
-  const progressError = (
-    status.progress as unknown as Record<string, unknown> | undefined
-  )?.error;
-  if (progressError && typeof progressError === 'string') {
-    lines.push(`  error: ${progressError.slice(0, 200)}`);
-  }
-
-  const renderedServerView = renderServerResultView(status.resultView);
-  if (result) {
-    lines.push(...formatReturnValue(result));
-  }
-  if (renderedServerView.lines.length > 0) {
-    lines.push(...renderedServerView.lines);
-  }
-  lines.push(...renderedServerView.actions);
-
-  console.log(lines.join('\n'));
-}
-
-function exportPlayStatusRows(
-  status: PlayStatus,
-  outPath: string | null,
-): string | null {
-  if (!outPath) {
-    return null;
-  }
-  const rowsInfo = extractCanonicalRowsInfo(status);
-  if (!rowsInfo) {
-    throw new DeeplineError(
-      `Run ${status.runId} did not expose a row-shaped final output to export.`,
-    );
-  }
-  return writeCanonicalRowsCsv(rowsInfo, outPath);
-}
-
-function renderServerResultView(value: unknown): {
-  lines: string[];
-  actions: string[];
-} {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    return { lines: [], actions: [] };
-  }
-  const view = value as {
-    render?: {
-      sections?: Array<{ title?: unknown; lines?: unknown }>;
-      actions?: Array<{ label?: unknown; command?: unknown }>;
-    };
-    scalars?: Array<{ key?: unknown; value?: unknown }>;
-    byStep?: Array<{ stepId?: unknown; count?: unknown; rate?: unknown }>;
-    tables?: Array<{
-      tableNamespace?: unknown;
-      rowCount?: unknown;
-      sourceLines?: unknown;
-      inputFields?: unknown;
-      outputFields?: unknown;
-      waterfallIds?: unknown;
-      columnCounts?: unknown;
-    }>;
-    datasetAccess?: {
-      sqlTableName?: unknown;
-      tableNamespace?: unknown;
-      sqlSchemaName?: unknown;
-      cliCommand?: unknown;
-      toolCommand?: unknown;
-      api?: unknown;
-      note?: unknown;
-    } | null;
-  };
-  const renderedSections = Array.isArray(view.render?.sections)
-    ? view.render.sections
-    : [];
-  const renderedActions = Array.isArray(view.render?.actions)
-    ? view.render.actions
-    : [];
-  if (renderedSections.length > 0 || renderedActions.length > 0) {
-    const lines: string[] = [];
-    for (const section of renderedSections) {
-      if (typeof section.title !== 'string') {
-        continue;
-      }
-      const sectionLines = Array.isArray(section.lines)
-        ? section.lines.filter(
-            (line): line is string => typeof line === 'string',
-          )
-        : [];
-      if (sectionLines.length === 0) {
-        continue;
-      }
-      lines.push(`  ${section.title}:`);
-      lines.push(...sectionLines.map((line) => `    ${line}`));
-    }
-    const actions = renderedActions
-      .filter(
-        (action): action is { label: string; command: string } =>
-          typeof action.label === 'string' &&
-          typeof action.command === 'string',
-      )
-      .map((action) => `  ${action.label}: ${action.command}`);
-    return { lines, actions };
-  }
-
-  const lines = ['  execution statistics:'];
-  const scalars = Array.isArray(view.scalars) ? view.scalars : [];
-  const scalarParts = scalars
-    .filter((entry) => typeof entry.key === 'string')
-    .map((entry) => `${entry.key}=${formatInteger(entry.value)}`);
-  if (scalarParts.length > 0) {
-    lines.push(`    ${scalarParts.join('  ')}`);
-  }
-
-  const byStep = Array.isArray(view.byStep) ? view.byStep : [];
-  if (byStep.length > 0) {
-    lines.push(
-      `    byStep=${byStep
-        .slice(0, 8)
-        .map((entry) => {
-          const rate =
-            typeof entry.rate === 'number'
-              ? ` (${(entry.rate * 100).toFixed(entry.rate >= 0.1 ? 0 : 1)}%)`
-              : '';
-          return `${String(entry.stepId)}:${formatInteger(entry.count)}${rate}`;
-        })
-        .join(', ')}`,
-    );
-  }
-
-  const tables = Array.isArray(view.tables) ? view.tables : [];
-  if (tables.length > 0) {
-    lines.push('    tables:');
-    for (const table of tables.slice(0, 6)) {
-      const details = [
-        Array.isArray(table.inputFields) && table.inputFields.length
-          ? `inputs=${table.inputFields.join(',')}`
-          : null,
-        Array.isArray(table.outputFields) && table.outputFields.length
-          ? `outputs=${table.outputFields.join(',')}`
-          : null,
-        Array.isArray(table.waterfallIds) && table.waterfallIds.length
-          ? `waterfalls=${table.waterfallIds.join(',')}`
-          : null,
-        table.columnCounts &&
-        typeof table.columnCounts === 'object' &&
-        !Array.isArray(table.columnCounts)
-          ? `columns=${Object.entries(
-              table.columnCounts as Record<string, unknown>,
-            )
-              .map(([key, count]) => `${key}:${String(count)}`)
-              .join(',')}`
-          : null,
-      ].filter(Boolean);
-      const rowLabel =
-        typeof table.rowCount === 'number'
-          ? `rows=${formatInteger(table.rowCount)}  `
-          : '';
-      const lineLabel =
-        typeof table.sourceLines === 'string'
-          ? ` lines ${table.sourceLines}`
-          : '';
-      lines.push(
-        `    ${String(table.tableNamespace ?? 'table')}${lineLabel}: ${rowLabel}${details.join('  ')}`,
-      );
-    }
-  }
-
-  return { lines: lines.length > 1 ? lines : [], actions: [] };
-}
-
-function writeStartedPlayRun(input: {
-  runId: string;
-  playName: string;
-  status?: string;
-  statusUrl?: string;
-  dashboardUrl?: string;
-  jsonOutput: boolean;
-  progress?: CliProgress;
-}): void {
-  const payload = {
-    runId: input.runId,
-    workflowId: input.runId,
-    name: input.playName,
-    status: input.status ?? 'started',
-    statusUrl: input.statusUrl,
-    dashboardUrl: input.dashboardUrl,
-  };
-
-  if (input.jsonOutput) {
-    process.stdout.write(`${JSON.stringify(payload)}\n`);
-    return;
-  }
-
-  const lines = [
-    `Started ${input.playName}`,
-    `  run id: ${input.runId}`,
-    `  check status: deepline play status --run-id ${input.runId}`,
-    `  tail logs: deepline play tail --run-id ${input.runId}`,
-    `  stop run: deepline play stop --run-id ${input.runId}`,
-    `  result JSON: deepline play status --run-id ${input.runId} --json`,
-  ];
-
-  if (input.dashboardUrl) {
-    lines.push(`  play page: ${input.dashboardUrl}`);
-  }
-
-  const output = lines.join('\n');
-  if (input.progress) {
-    input.progress.writeLine(output, process.stdout);
-    return;
-  }
-  console.log(output);
-}
-
-function parsePlayRunOptions(args: string[]): PlayRunCommandOptions {
-  const usage =
-    "Usage: deepline plays run <play-name> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n" +
-    "       deepline plays run <play-file.ts> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n" +
-    "       deepline plays run --file <play-file.ts> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n" +
-    "       deepline plays run --name <name> [--input '{...}'] [--live|--latest|--revision-id <id>] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--json] [--<input> value]";
-  let filePath: string | null = null;
-  let playName: string | null = null;
-  let input: Record<string, unknown> | null = null;
-  let revisionId: string | null = null;
-  let revisionSelector: 'live' | 'latest' | null = null;
-  const watch = args.includes('--watch');
-  let jsonOutput = watch ? args.includes('--json') : argsWantJson(args);
-  const emitLogs = !jsonOutput || args.includes('--logs');
-  const force = args.includes('--force');
-  let outPath: string | null = null;
-  let pollIntervalMs = 500;
-  let waitTimeoutMs: number | null = null;
-
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index]!;
-    if (arg === '--file' && args[index + 1]) {
-      filePath = args[++index]!;
-      continue;
-    }
-    if (arg === '--name' && args[index + 1]) {
-      playName = parseReferencedPlayTarget(args[++index]!).playName;
-      continue;
-    }
-    if ((arg === '--input' || arg === '-i') && args[index + 1]) {
-      input = parseJsonInput(args[++index]!);
-      continue;
-    }
-    if (arg === '--revision-id' && args[index + 1]) {
-      revisionId = args[++index]!;
-      continue;
-    }
-    if (arg === '--live') {
-      revisionSelector = 'live';
-      continue;
-    }
-    if (arg === '--latest') {
-      revisionSelector = 'latest';
-      continue;
-    }
-    if (arg === '--out' && args[index + 1]) {
-      outPath = resolve(args[++index]!);
-      continue;
-    }
-    if (
-      (arg === '--poll-interval-ms' || arg === '--interval-ms') &&
-      args[index + 1]
-    ) {
-      pollIntervalMs = parsePositiveInteger(args[++index]!, arg);
-      continue;
-    }
-    if (
-      (arg === '--tail-timeout-ms' || arg === '--timeout-ms') &&
-      args[index + 1]
-    ) {
-      waitTimeoutMs = parsePositiveInteger(args[++index]!, arg);
-      continue;
-    }
-    if (
-      arg === '--json' ||
-      arg === '--wait' ||
-      arg === '--tail' ||
-      arg === '--watch' ||
-      arg === '--logs' ||
-      arg === '--force'
-    ) {
-      if (arg === '--watch') {
-        continue;
-      }
-      if (arg === '--json') {
-        jsonOutput = true;
-        continue;
-      }
-      if (arg === '--wait') {
-        throw new Error(
-          '--wait is removed for `plays run`; use `--watch` to stream completion output.',
-        );
-      }
-      if (arg === '--tail') {
-        throw new Error(
-          '--tail is removed for `plays run`; use `--watch` to stream completion output.',
-        );
-      }
-      continue;
-    }
-    if (arg.startsWith('--')) {
-      const { path, value } = parseInputFieldFlag(arg, args[index + 1]);
-      input ??= {};
-      setDottedInputValue(input, path, parseInputFlagValue(value));
-      if (!arg.includes('=')) {
-        index += 1;
-      }
-      continue;
-    }
-    if (!arg.startsWith('--') && !filePath && !playName) {
-      if (isFileTarget(arg) || looksLikeFilePath(arg)) {
-        filePath = arg;
-      } else {
-        playName = parseReferencedPlayTarget(arg).playName;
-      }
-      continue;
-    }
-  }
-
-  if ((filePath && playName) || (!filePath && !playName)) {
-    throw new Error(usage);
-  }
-  const explicitRevisionSelectors = [
-    revisionId ? '--revision-id' : null,
-    revisionSelector === 'live' ? '--live' : null,
-    revisionSelector === 'latest' ? '--latest' : null,
-  ].filter(Boolean);
-  if (explicitRevisionSelectors.length > 1) {
-    throw new Error(
-      `Choose only one revision selector: ${explicitRevisionSelectors.join(', ')}.`,
-    );
-  }
-  if (filePath && explicitRevisionSelectors.length > 0) {
-    throw new Error(
-      '--live, --latest, and --revision-id only apply to named plays.',
-    );
-  }
-  if (outPath && !watch) {
-    throw new Error(
-      '--out requires --watch so the CLI can export the completed run output.',
-    );
-  }
-
-  return {
-    target: filePath
-      ? { kind: 'file', path: filePath }
-      : { kind: 'name', name: playName! },
-    input,
-    revisionId,
-    revisionSelector,
-    watch,
-    emitLogs,
-    jsonOutput,
-    pollIntervalMs,
-    waitTimeoutMs,
-    force,
-    outPath,
-  };
-}
-
-function parsePlayCheckOptions(args: string[]): PlayCheckCommandOptions {
-  const target = args[0];
-  if (!target) {
-    throw new Error('Usage: deepline play check <play-file.ts> [--json]');
-  }
-
-  const jsonOutput = argsWantJson(args);
-  return { target, jsonOutput };
-}
-
-export async function handlePlayCheck(args: string[]): Promise<number> {
-  const options = parsePlayCheckOptions(args);
-  if (!isFileTarget(options.target)) {
-    const resolved = resolve(options.target);
-    console.error(`File not found: ${resolved}`);
-    return 1;
-  }
-
-  const absolutePlayPath = resolve(options.target);
-  const sourceCode = readFileSync(absolutePlayPath, 'utf-8');
-  let graph: {
-    root: BundledPlayFileSuccess;
-    nodes: Map<string, BundledPlayFileSuccess>;
-  };
-  try {
-    graph = await collectBundledPlayGraph(absolutePlayPath);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (options.jsonOutput) {
-      process.stdout.write(
-        `${JSON.stringify({ valid: false, stage: 'bundle', errors: [message] })}\n`,
-      );
-    } else {
-      console.error(message);
-    }
-    return 1;
-  }
-
-  const playName =
-    graph.root.playName ?? extractPlayName(sourceCode, absolutePlayPath);
-  const client = new DeeplineClient();
-  const result = await client.checkPlayArtifact({
-    name: playName,
-    sourceCode: graph.root.sourceCode,
-    artifact: graph.root.artifact,
-  });
-
-  if (options.jsonOutput) {
-    process.stdout.write(`${JSON.stringify({ name: playName, ...result })}\n`);
-  } else if (result.valid) {
-    console.log(`✓ ${playName} passed cloud play check`);
-    if (result.artifactHash) {
-      console.log(`  artifact: ${result.artifactHash.slice(0, 12)}`);
-    }
-  } else {
-    console.error(`✗ ${playName} failed cloud play check`);
-    for (const error of result.errors) {
-      console.error(`  ${error}`);
-    }
-  }
-
-  return result.valid ? 0 : 1;
-}
-
-async function handleFileBackedRun(
-  options: PlayRunCommandOptions,
-): Promise<number> {
-  if (options.target.kind !== 'file') {
-    throw new Error('Expected a file-backed play run target.');
-  }
-  const client = new DeeplineClient();
-  const progress =
-    getActiveCliProgress() ?? createCliProgress(!options.jsonOutput);
-  const absolutePlayPath = resolve(options.target.path);
-  progress.phase('compiling play');
-  const sourceCode = readFileSync(absolutePlayPath, 'utf-8');
-  let graph: {
-    root: BundledPlayFileSuccess;
-    nodes: Map<string, BundledPlayFileSuccess>;
-  };
-  try {
-    graph = await collectBundledPlayGraph(absolutePlayPath);
-    await compileBundledPlayGraphManifests(client, graph);
-    progress.phase('compiled play');
-  } catch (error) {
-    progress.fail();
-    console.error(error instanceof Error ? error.message : String(error));
-    return 1;
-  }
-
-  const bundleResult = graph.root;
-  const playName =
-    bundleResult.playName ?? extractPlayName(sourceCode, absolutePlayPath);
-
-  try {
-    progress.phase('publishing imported plays');
-    await publishImportedPlayDependencies(client, graph);
-  } catch (error) {
-    progress.fail();
-    console.error(error instanceof Error ? error.message : String(error));
-    return 1;
-  }
-
-  const runtimeInput = options.input ? { ...options.input } : {};
-  const packagedFileUploads = bundleResult.packagedFiles.map((file) =>
-    stageFile(file.logicalPath, file.absolutePath),
-  );
-  const stagedFileInputs = await stageFileInputArgs({
-    client,
-    runtimeInput,
-    bindings: fileInputBindingsFromStaticPipeline(
-      requireCompilerManifest(bundleResult).staticPipeline,
-    ),
-    progress,
-  });
-
-  const startRequest = {
-    name: playName,
-    sourceCode: bundleResult.sourceCode,
-    runtimeArtifact: bundleResult.artifact,
-    compilerManifest: requireCompilerManifest(bundleResult),
-    packagedFileUploads,
-    ...(Object.keys(runtimeInput).length > 0 ? { input: runtimeInput } : {}),
-    ...(stagedFileInputs.inputFile
-      ? { inputFile: stagedFileInputs.inputFile }
-      : {}),
-    ...(stagedFileInputs.packagedFiles.length
-      ? { packagedFiles: stagedFileInputs.packagedFiles }
-      : {}),
-    ...(options.force ? { force: true } : {}),
-  };
-
-  if (options.watch) {
-    progress.phase('starting run');
-    const finalStatus = await startAndWaitForPlayCompletionByStream({
-      client,
-      request: startRequest,
-      playName,
-      jsonOutput: options.jsonOutput,
-      emitLogs: options.emitLogs,
-      waitTimeoutMs: options.waitTimeoutMs,
-      progress,
-    });
-    const exportedPath = exportPlayStatusRows(finalStatus, options.outPath);
-    if (finalStatus.status === 'completed') {
-      progress.complete();
-    } else {
-      progress.fail();
-    }
-    writePlayResult(finalStatus, options.jsonOutput, { exportedPath });
-    return finalStatus.status === 'completed' ? 0 : 1;
-  }
-
-  progress.phase('starting run');
-  const started = await client.startPlayRun(startRequest);
-  const dashboardUrl = buildPlayDashboardUrl(client.baseUrl, playName);
-  progress.phase(`loading play on ${dashboardUrl}`);
-  progress.complete();
-
-  writeStartedPlayRun({
-    runId: started.workflowId,
-    playName,
-    status: started.status,
-    statusUrl: started.statusUrl,
-    dashboardUrl: started.dashboardUrl ?? dashboardUrl,
-    jsonOutput: options.jsonOutput,
-    progress,
-  });
-  return 0;
-}
-
-async function resolveNamedRunRevisionId(input: {
-  client: DeeplineClient;
-  playName: string;
-  revisionId: string | null;
-  selector: 'live' | 'latest' | null;
-}): Promise<string | null> {
-  if (input.revisionId) {
-    return input.revisionId;
-  }
-  if (input.selector === 'latest') {
-    const versions = await input.client.listPlayVersions(input.playName);
-    const latest = versions[0];
-    if (!latest?._id) {
-      throw new Error(`No saved revisions found for ${input.playName}.`);
-    }
-    return latest._id;
-  }
-  return null;
-}
-
-async function handleNamedRun(options: PlayRunCommandOptions): Promise<number> {
-  if (options.target.kind !== 'name') {
-    throw new Error('Expected a named play run target.');
-  }
-  const client = new DeeplineClient();
-  const progress =
-    getActiveCliProgress() ?? createCliProgress(!options.jsonOutput);
-
-  progress.phase('loading play definition');
-  const playDetail = await assertCanonicalNamedPlayReference(client, options.target.name);
-  progress.phase('selecting revision');
-  const selectedRevisionId = await resolveNamedRunRevisionId({
-    client,
-    playName: options.target.name,
-    revisionId: options.revisionId,
-    selector: options.revisionSelector,
-  });
-
-  const runtimeInput = options.input ? { ...options.input } : {};
-  const stagedFileInputs = await stageFileInputArgs({
-    client,
-    runtimeInput,
-    bindings: [
-      ...fileInputBindingsFromPlaySchema(playDetail.play.inputSchema),
-      ...fileInputBindingsFromStaticPipeline(playDetail.play.staticPipeline),
-    ],
-    progress,
-  });
-
-  const startRequest = {
-    name: options.target.name,
-    ...(selectedRevisionId ? { revisionId: selectedRevisionId } : {}),
-    ...(Object.keys(runtimeInput).length > 0 ? { input: runtimeInput } : {}),
-    ...(stagedFileInputs.inputFile
-      ? { inputFile: stagedFileInputs.inputFile }
-      : {}),
-    ...(stagedFileInputs.packagedFiles.length
-      ? { packagedFiles: stagedFileInputs.packagedFiles }
-      : {}),
-    ...(options.force ? { force: true } : {}),
-  };
-
-  if (options.watch) {
-    progress.phase('starting run');
-    const finalStatus = await startAndWaitForPlayCompletionByStream({
-      client,
-      request: startRequest,
-      playName: options.target.name,
-      jsonOutput: options.jsonOutput,
-      emitLogs: options.emitLogs,
-      waitTimeoutMs: options.waitTimeoutMs,
-      progress,
-    });
-    const exportedPath = exportPlayStatusRows(finalStatus, options.outPath);
-    if (finalStatus.status === 'completed') {
-      progress.complete();
-    } else {
-      progress.fail();
-    }
-    writePlayResult(finalStatus, options.jsonOutput, { exportedPath });
-    return finalStatus.status === 'completed' ? 0 : 1;
-  }
-
-  progress.phase('starting run');
-  const started = await client.startPlayRun(startRequest);
-  const dashboardUrl = buildPlayDashboardUrl(
-    client.baseUrl,
-    options.target.name,
-  );
-  progress.phase(`loading play on ${dashboardUrl}`);
-  progress.complete();
-
-  writeStartedPlayRun({
-    runId: started.workflowId,
-    playName: started.name ?? options.target.name,
-    status: started.status,
-    statusUrl: started.statusUrl,
-    dashboardUrl: started.dashboardUrl ?? dashboardUrl,
-    jsonOutput: options.jsonOutput,
-    progress,
-  });
-  return 0;
-}
-
-export async function handlePlayRun(args: string[]): Promise<number> {
-  const options = parsePlayRunOptions(args);
-  if (options.target.kind === 'file') {
-    if (isFileTarget(options.target.path)) {
-      return handleFileBackedRun(options);
-    }
-    const resolved = resolve(options.target.path);
-    console.error(`File not found: ${resolved}`);
-    // Suggest close matches
-    const dir = dirname(resolved);
-    if (existsSync(dir)) {
-      const base = basename(resolved);
-      try {
-        const siblings = 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(`  ${join(dir, s)}`);
-          }
-        }
-      } catch {}
-    }
-    return 1;
-  }
-  return handleNamedRun(options);
-}
-
-export async function handlePlayTail(args: string[]): Promise<number> {
-  const usage =
-    'Usage: deepline play tail --run-id <run-id> [--interval-ms 1000] [--json]\n' +
-    '       deepline play tail --name <name> [--interval-ms 1000] [--json]';
-  let target: PlayRunTarget;
-  try {
-    target = parsePlayRunTarget({ args, usage, allowName: true });
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : usage);
-    return 1;
-  }
-
-  const client = new DeeplineClient();
-  const jsonOutput = argsWantJson(args);
-  const emitLogs = !jsonOutput || args.includes('--logs');
-  let intervalMs = 500;
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index]!;
-    if (
-      (arg === '--interval-ms' || arg === '--poll-interval-ms') &&
-      args[index + 1]
-    ) {
-      intervalMs = parsePositiveInteger(args[++index]!, arg);
-    }
-  }
-
-  const workflowId = await resolvePlayRunId(client, target);
-  const progress = getActiveCliProgress() ?? createCliProgress(!jsonOutput);
-  progress.phase(`tailing ${workflowId}`);
-  const finalStatus = await waitForPlayCompletion({
-    client,
-    workflowId,
-    pollIntervalMs: intervalMs,
-    jsonOutput,
-    emitLogs,
-    waitTimeoutMs: null,
-    progress,
-  });
-
-  if (finalStatus.status === 'completed') {
-    progress.complete();
-  } else {
-    progress.fail();
-  }
-  writePlayResult(finalStatus, jsonOutput);
-  return finalStatus.status === 'completed' ? 0 : 1;
-}
-
-export async function handlePlayStatus(args: string[]): Promise<number> {
-  const usage =
-    'Usage: deepline play status --run-id <run-id> [--json] [--full]\n' +
-    '       deepline play status --name <name> [--json] [--full]';
-  let target: PlayRunTarget;
-  try {
-    target = parsePlayRunTarget({ args, usage, allowName: true });
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : usage);
-    return 1;
-  }
-
-  const client = new DeeplineClient();
-  const workflowId = await resolvePlayRunId(client, target);
-  const status = await client.getPlayStatus(workflowId);
-  writePlayResult(status, argsWantJson(args), {
-    fullJson: args.includes('--full'),
-  });
-  return 0;
-}
-
-function parseRunIdPositional(args: string[], usage: string): string {
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index]!;
-    if (arg === '--json' || arg === '--full' || arg === '--logs') {
-      continue;
-    }
-    if (arg === '--out' && args[index + 1]) {
-      index += 1;
-      continue;
-    }
-    if (!arg.startsWith('--')) {
-      return arg;
-    }
-  }
-  throw new DeeplineError(usage);
-}
-
-export async function handleRunStatus(args: string[]): Promise<number> {
-  const usage = 'Usage: deepline runs status <run-id> [--json] [--full]';
-  let runId: string;
-  try {
-    runId = parseRunIdPositional(args, usage);
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : usage);
-    return 1;
-  }
-  const client = new DeeplineClient();
-  const status = await client.getPlayStatus(runId);
-  writePlayResult(status, argsWantJson(args), {
-    fullJson: args.includes('--full'),
-  });
-  return 0;
-}
-
-export async function handleRunLogs(args: string[]): Promise<number> {
-  const usage = 'Usage: deepline runs logs <run-id> [--json]';
-  let runId: string;
-  try {
-    runId = parseRunIdPositional(args, usage);
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : usage);
-    return 1;
-  }
-  const client = new DeeplineClient();
-  const status = await client.getPlayStatus(runId);
-  const logs = status.progress?.logs ?? [];
-  if (argsWantJson(args)) {
-    process.stdout.write(`${JSON.stringify({ runId: status.runId, logs })}\n`);
-  } else {
-    process.stdout.write(`${logs.join('\n')}${logs.length > 0 ? '\n' : ''}`);
-  }
-  return 0;
-}
-
-export async function handleRunExport(args: string[]): Promise<number> {
-  const usage =
-    'Usage: deepline runs export <run-id> --out output.csv [--json]';
-  let runId: string;
-  try {
-    runId = parseRunIdPositional(args, usage);
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : usage);
-    return 1;
-  }
-  let outPath: string | null = null;
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index]!;
-    if (arg === '--out' && args[index + 1]) {
-      outPath = resolve(args[++index]!);
-    }
-  }
-  if (!outPath) {
-    console.error(usage);
-    return 1;
-  }
-  const client = new DeeplineClient();
-  const status = await client.getPlayStatus(runId);
-  const exportedPath = exportPlayStatusRows(status, outPath);
-  if (argsWantJson(args)) {
-    const rowsInfo = extractCanonicalRowsInfo(status);
-    process.stdout.write(
-      `${JSON.stringify({
-        runId: status.runId,
-        csv_path: exportedPath,
-        rowCount: rowsInfo?.totalRows ?? null,
-        columns: rowsInfo?.columns ?? [],
-      })}\n`,
-    );
-  } else {
-    console.log(`Exported ${status.runId} to ${exportedPath}`);
-  }
-  return 0;
-}
-
-export async function handlePlayStop(args: string[]): Promise<number> {
-  const usage =
-    'Usage: deepline play stop --run-id <run-id> [--reason "text"] [--json]';
-  let target: PlayRunTarget;
-  try {
-    target = parsePlayRunTarget({ args, usage, allowName: false });
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : usage);
-    return 1;
-  }
-
-  const client = new DeeplineClient();
-  const jsonOutput = argsWantJson(args);
-  let reason: string | undefined;
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index]!;
-    if (arg === '--reason' && args[index + 1]) {
-      reason = args[++index]!;
-    }
-  }
-
-  const workflowId = await resolvePlayRunId(client, target);
-  const result = await client.stopPlay(workflowId, { reason });
-  if (jsonOutput) {
-    process.stdout.write(`${JSON.stringify(result)}\n`);
-  } else {
-    console.log(`Stopped ${result.runId}`);
-    if (result.hitlCancelledCount > 0) {
-      console.log(`  cancelled HITL waits: ${result.hitlCancelledCount}`);
-    }
-  }
-  return 0;
-}
-
-export async function handlePlayGet(args: string[]): Promise<number> {
-  const target = args[0];
-  if (!target) {
-    console.error('Usage: deepline play get <play-file.ts|play-name> [--json]');
-    return 1;
-  }
-
-  const client = new DeeplineClient();
-  const explicitJson = args.includes('--json');
-  const sourceOutput = args.includes('--source');
-  const jsonOutput = sourceOutput ? explicitJson : argsWantJson(args);
-  let outPath: string | null = null;
-  for (let index = 1; index < args.length; index += 1) {
-    const arg = args[index]!;
-    if (arg === '--out' && args[index + 1]) {
-      outPath = resolve(args[++index]!);
-    }
-  }
-  const playName = isFileTarget(target)
-    ? extractPlayName(readFileSync(resolve(target), 'utf-8'), 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({
-          target,
-          playName,
-          sourceCode: resolvedSource,
-          outPath,
-        })
-      : null;
-  const loadedMessage = materializedFile
-    ? formatLoadedPlayMessage(materializedFile)
-    : null;
-
-  if (jsonOutput) {
-    process.stdout.write(
-      `${JSON.stringify({
-        ...detail,
-        ...(materializedFile
-          ? {
-              message: loadedMessage,
-              materializedFile: {
-                path: materializedFile.path,
-                created: materializedFile.created,
-                status: materializedFile.status,
-                message: loadedMessage,
-              },
-            }
-          : {}),
-      })}\n`,
-    );
-    return 0;
-  }
-
-  if (sourceOutput) {
-    if (!resolvedSource.trim()) {
-      console.error(`No source code available for ${playName}.`);
-      return 1;
-    }
-    if (materializedFile) {
-      console.log(loadedMessage);
-      return 0;
-    }
-    process.stdout.write(resolvedSource);
-    if (!resolvedSource.endsWith('\n')) {
-      process.stdout.write('\n');
-    }
-    return 0;
-  }
-
-  if (outPath && loadedMessage) {
-    console.log(loadedMessage);
-    return 0;
-  }
-
-  console.log(`Play: ${formatPlayReference(detail.play)}`);
-  console.log(
-    `Working version: ${detail.play.workingRevision?.version ?? '—'}`,
-  );
-  console.log(`Live version: ${detail.play.liveRevision?.version ?? '—'}`);
-  console.log(`Draft dirty: ${detail.play.isDraftDirty ? 'yes' : 'no'}`);
-  console.log(`Runs: ${detail.latestRuns.length}`);
-  console.log(`Updated: ${formatTimestamp(detail.play.updatedAt)}`);
-  console.log(`Sheet rows: ${detail.sheetSummary?.stats?.total ?? 0}`);
-  if (detail.customerDbUrl) {
-    console.log(`Customer DB: ${detail.customerDbUrl}`);
-  }
-  if (materializedFile) {
-    console.log(loadedMessage);
-  }
-  if (detail.latestRuns.length > 0) {
-    console.log('Latest runs:');
-    for (const run of detail.latestRuns.slice(0, 5)) {
-      console.log(`  ${formatRunLine(run)}`);
-    }
-  }
-  return 0;
-}
-
-export async function handlePlayRuns(args: string[]): Promise<number> {
-  const nameIndex = args.indexOf('--name');
-  const name = nameIndex >= 0 ? args[nameIndex + 1] : undefined;
-  if (!name) {
-    console.error('Usage: deepline play runs --name <name> [--json]');
-    return 1;
-  }
-
-  const client = new DeeplineClient();
-  const jsonOutput = argsWantJson(args);
-  await assertCanonicalNamedPlayReference(client, name);
-  const runs = await client.listPlayRuns(
-    parseReferencedPlayTarget(name).playName,
-  );
-  if (jsonOutput) {
-    process.stdout.write(`${JSON.stringify({ runs })}\n`);
-    return 0;
-  }
-
-  if (runs.length === 0) {
-    console.log(`No runs found for ${name}.`);
-    return 0;
-  }
-
-  for (const run of runs) {
-    console.log(formatRunLine(run));
-  }
-  return 0;
-}
-
-function formatVersionLine(version: PlayRevisionSummary): string {
-  const revisionLabel =
-    version.artifactHash?.slice(0, 12) ?? 'unknown-revision';
-  return `v${version.version} ${revisionLabel} ${formatTimestamp(version.createdAt)}`;
-}
-
-export async function handlePlayVersions(args: string[]): Promise<number> {
-  const nameIndex = args.indexOf('--name');
-  const playName = nameIndex >= 0 ? args[nameIndex + 1] : undefined;
-  if (!playName) {
-    console.error('Usage: deepline play versions --name <name> [--json]');
-    return 1;
-  }
-
-  const client = new DeeplineClient();
-  const jsonOutput = argsWantJson(args);
-  await assertCanonicalNamedPlayReference(client, playName);
-  const versions = await client.listPlayVersions(
-    parseReferencedPlayTarget(playName).playName,
-  );
-  if (jsonOutput) {
-    process.stdout.write(`${JSON.stringify({ versions })}\n`);
-    return 0;
-  }
-
-  if (versions.length === 0) {
-    console.log(`No versions found for ${playName}.`);
-    return 0;
-  }
-
-  for (const version of versions) {
-    console.log(formatVersionLine(version));
-  }
-  return 0;
-}
-
-export async function handlePlayList(args: string[]): Promise<number> {
-  const jsonOutput = argsWantJson(args);
-  const client = new DeeplineClient();
-  const plays = await client.listPlays();
-
-  if (jsonOutput) {
-    process.stdout.write(`${JSON.stringify(plays)}\n`);
-    return 0;
-  }
-
-  process.stdout.write(`${plays.length} plays available:\n\n`);
-  for (const play of plays) {
-    const flags = [
-      play.origin === 'prebuilt' || play.ownerType === 'deepline'
-        ? 'prebuilt'
-        : 'owned',
-      play.canEdit ? 'editable' : 'readonly',
-      play.isDraftDirty ? 'draft-dirty' : null,
-    ]
-      .filter(Boolean)
-      .join(', ');
-    const reference = formatPlayListReference(play);
-    process.stdout.write(`  ${reference}${flags ? ` [${flags}]` : ''}\n`);
-    if (play.inputSchema) {
-      process.stdout.write('    inputSchema: yes\n');
-    }
-    process.stdout.write(`    run: deepline plays run ${reference} --watch\n`);
-  }
-  return 0;
-}
-
-function parsePlaySearchOptions(args: string[]): PlaySearchOptions {
-  const query = args[0]?.trim();
-  if (!query) {
-    throw new Error(
-      'Usage: deepline plays search <query> [--origin prebuilt|owned] [--compact] [--json]',
-    );
-  }
-
-  let origin: 'prebuilt' | 'owned' | undefined;
-  for (let index = 1; index < args.length; index += 1) {
-    const arg = args[index]!;
-    if (arg === '--origin' && args[index + 1]) {
-      const rawOrigin = args[++index]!.trim().toLowerCase();
-      if (rawOrigin !== 'prebuilt' && rawOrigin !== 'owned') {
-        throw new Error(`Invalid value for --origin: ${rawOrigin}`);
-      }
-      origin = rawOrigin;
-    }
-  }
-
-  return {
-    query,
-    jsonOutput: argsWantJson(args),
-    compact: args.includes('--compact'),
-    origin,
-  };
-}
-
-function printPlayDescription(play: PlayDescription): void {
-  const reference = formatPlayListReference(play);
-  const labels = [
-    play.origin ?? null,
-    play.ownerType ?? null,
-    play.canEdit ? 'editable' : 'readonly',
-    play.isDraftDirty ? 'draft-dirty' : null,
-  ].filter(Boolean);
-  console.log(
-    `Play: ${reference}${labels.length ? ` [${labels.join(', ')}]` : ''}`,
-  );
-  if (play.displayName && play.displayName !== play.name) {
-    console.log(`  Display name: ${play.displayName}`);
-  }
-  if (play.aliases.length > 0) {
-    console.log(`  Aliases: ${play.aliases.join(', ')}`);
-  }
-  if (play.inputSchema) {
-    console.log('  Input schema:');
-    const rendered = JSON.stringify(play.inputSchema, null, 2);
-    for (const line of rendered.split('\n')) {
-      console.log(`    ${line}`);
-    }
-  }
-  if (play.outputSchema) {
-    console.log('  Output schema:');
-    const rendered = JSON.stringify(play.outputSchema, null, 2);
-    for (const line of rendered.split('\n')) {
-      console.log(`    ${line}`);
-    }
-  }
-  if (play.csvInput) {
-    console.log('  CSV input:');
-    const rendered = JSON.stringify(play.csvInput, null, 2);
-    for (const line of rendered.split('\n')) {
-      console.log(`    ${line}`);
-    }
-  }
-  if (play.rowOutputSchema) {
-    console.log('  Row output schema:');
-    const rendered = JSON.stringify(play.rowOutputSchema, null, 2);
-    for (const line of rendered.split('\n')) {
-      console.log(`    ${line}`);
-    }
-  }
-  console.log(`  Run: ${play.runCommand}`);
-}
-
-export async function handlePlaySearch(args: string[]): Promise<number> {
-  let options: PlaySearchOptions;
-  try {
-    options = parsePlaySearchOptions(args);
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    return 1;
-  }
-
-  const client = new DeeplineClient();
-  const plays = await client.searchPlays({
-    query: options.query,
-    ...(options.origin ? { origin: options.origin } : {}),
-    compact: options.compact,
-  });
-
-  if (options.jsonOutput) {
-    process.stdout.write(`${JSON.stringify({ plays })}\n`);
-    return 0;
-  }
-
-  process.stdout.write(`${plays.length} plays found:\n\n`);
-  for (const play of plays) {
-    printPlayDescription(play);
-    console.log('');
-  }
-  return 0;
-}
-
-export async function handlePlayDescribe(args: string[]): Promise<number> {
-  const playName = args[0];
-  if (!playName) {
-    console.error(
-      'Usage: deepline plays describe <play-name> [--compact] [--json]',
-    );
-    return 1;
-  }
-
-  const client = new DeeplineClient();
-  await assertCanonicalNamedPlayReference(client, playName);
-  const play = await client.describePlay(
-    parseReferencedPlayTarget(playName).playName,
-    {
-      compact: args.includes('--compact'),
-    },
-  );
-
-  if (argsWantJson(args)) {
-    process.stdout.write(`${JSON.stringify(play)}\n`);
-    return 0;
-  }
-
-  printPlayDescription(play);
-  return 0;
-}
-
-export async function handlePlayPublish(args: string[]): Promise<number> {
-  const playName = args[0];
-  if (!playName) {
-    console.error(
-      'Usage: deepline play publish <play-file.ts|play-name> [--latest|--revision-id <id>] [--json]',
-    );
-    return 1;
-  }
-
-  let revisionId: string | undefined;
-  let useLatest = false;
-  for (let index = 1; index < args.length; index += 1) {
-    const arg = args[index]!;
-    if (arg === '--revision-id' && args[index + 1]) {
-      revisionId = args[++index]!;
-    }
-    if (arg === '--latest') {
-      useLatest = true;
-    }
-  }
-  if (revisionId && useLatest) {
-    console.error('Choose only one live target: --latest or --revision-id.');
-    return 1;
-  }
-
-  const client = new DeeplineClient();
-  if (isFileTarget(playName)) {
-    if (revisionId || useLatest) {
-      console.error(
-        '--latest and --revision-id cannot be used when the target is a local play file.',
-      );
-      return 1;
-    }
-
-    let graph: {
-      root: BundledPlayFileSuccess;
-      nodes: Map<string, BundledPlayFileSuccess>;
-    };
-    try {
-      graph = await collectBundledPlayGraph(resolve(playName));
-      await compileBundledPlayGraphManifests(client, graph);
-      await publishImportedPlayDependencies(client, graph);
-    } catch (error) {
-      console.error(error instanceof Error ? error.message : String(error));
-      return 1;
-    }
-
-    const rootPlayName =
-      graph.root.playName ??
-      extractPlayName(graph.root.sourceCode, graph.root.filePath);
-    const published = await client.registerPlayArtifact({
-      name: rootPlayName,
-      sourceCode: graph.root.sourceCode,
-      artifact: graph.root.artifact,
-      compilerManifest: requireCompilerManifest(graph.root),
-      publish: true,
-    });
-    process.stdout.write(
-      `${JSON.stringify({
-        success: true,
-        name: rootPlayName,
-        liveVersion: published.version ?? null,
-        revisionId: published.revisionId ?? null,
-        triggerMetadata: published.triggerMetadata ?? null,
-        triggerBindings: published.triggerBindings ?? [],
-      })}\n`,
-    );
-    return 0;
-  }
-
-  const resolvedName = parseReferencedPlayTarget(playName).playName;
-  if (useLatest) {
-    const versions = await client.listPlayVersions(resolvedName);
-    const latest = versions[0];
-    if (!latest?._id) {
-      console.error(`No saved revisions found for ${resolvedName}.`);
-      return 1;
-    }
-    revisionId = latest._id;
-  }
-  try {
-    await ensureEditableRemotePlay(client, resolvedName);
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    return 1;
-  }
-  const result = await client.publishPlayVersion(
-    resolvedName,
-    revisionId ? { revisionId } : {},
-  );
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-  return result.success ? 0 : 1;
-}
-
-export async function handlePlayDelete(args: string[]): Promise<number> {
-  const playName = args[0];
-  if (!playName) {
-    console.error('Usage: deepline plays delete <play-name> --yes [--json]');
-    return 1;
-  }
-  const confirmed =
-    args.includes('--yes') || args.includes('-y') || args.includes('--force');
-  if (!confirmed) {
-    console.error(
-      'Refusing to delete without --yes. This deletes the org-owned play, its revisions, trigger bindings, and local run records.',
-    );
-    return 1;
-  }
-
-  const client = new DeeplineClient();
-  let detail: PlayDetail;
-  try {
-    detail = await client.getPlay(parseReferencedPlayTarget(playName).playName);
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    return 1;
-  }
-  if (detail.play.ownerType === 'deepline' || detail.play.origin === 'prebuilt') {
-    console.error(`Cannot delete prebuilt play: ${formatPlayReference(detail.play)}`);
-    return 1;
-  }
-
-  const result = await client.deletePlay(
-    parseReferencedPlayTarget(formatPlayReference(detail.play)).playName,
-  );
-  if (argsWantJson(args)) {
-    process.stdout.write(`${JSON.stringify(result)}\n`);
-    return result.deleted ? 0 : 1;
-  }
-  process.stdout.write(
-    `Deleted ${result.name}: revisions=${result.deletedRevisionCount}, bindings=${result.deletedBindingCount}, runs=${result.deletedRunCount}\n`,
-  );
-  return result.deleted ? 0 : 1;
-}
-
-export function registerPlayCommands(program: Command): void {
-  const play = program
-    .command('plays')
-    .alias('play')
-    .description('Search, validate, run, and manage cloud plays.')
-    .addHelpText(
-      'after',
-      `
-Concepts:
-  Plays are durable Deepline cloud workflows. Local .play.ts files are bundled locally,
-  then validated and executed in Deepline cloud.
-
-Common commands:
-  deepline plays search email --json
-  deepline plays describe person-linkedin-to-email --json
-  deepline plays check my.play.ts
-  deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
-  deepline plays get person-linkedin-to-email --json
-`,
-    );
-
-  play
-    .command('check <target>')
-    .description('Bundle-check a local play file.')
-    .addHelpText(
-      'after',
-      `
-Notes:
-  Validates a local play without storing it, promoting it, or starting a run.
-  This uses the authoritative cloud preflight path.
-
-Examples:
-  deepline plays check my.play.ts
-  deepline plays check my.play.ts --json
-`,
-    )
-    .option('--json', 'Emit JSON output. Also automatic when stdout is piped')
-    .action(async (target, options) => {
-      process.exitCode = await handlePlayCheck([
-        target,
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-
-  play
-    .command('run [target]')
-    .description('Run a play file or named play.')
-    .allowUnknownOption(true)
-    .allowExcessArguments(true)
-    .addHelpText(
-      'after',
-      `
-Notes:
-	  Local play files are bundled locally, then validated and executed in Deepline cloud.
-	  Named plays run the stored live cloud revision.
-	  Unknown --foo and --foo.bar flags are treated as play input args.
-	  File-like input args accept local paths; the CLI stages those files before submit.
-	  Run performs server preflight automatically. Use \`deepline plays check <file>\`
-	  to validate without starting a run.
-
-Examples:
-  deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
-  deepline plays run person-linkedin-to-email --input '{"linkedin_url":"..."}' --watch
-  deepline plays run enrich.play.ts --csv leads.csv --watch --out leads-enriched.csv
-`,
-    )
-    .option('--file <path>', 'Local play file to run')
-    .option('--name <name>', 'Saved play name to run')
-    .option('-i, --input <json>', 'Input JSON object or @file path')
-    .option('--live', 'Run the current live revision explicitly')
-    .option('--latest', 'Run the newest saved revision, even if it is not live')
-    .option(
-      '--revision-id <id>',
-      'Run a specific saved revision instead of the live revision',
-    )
-    .option(
-      '--out <path>',
-      'Write the completed row output to CSV; requires --watch',
-    )
-    .option('--watch', 'Stream logs until completion')
-    .option(
-      '--logs',
-      'When output is non-interactive, stream play logs to stderr while waiting',
-    )
-    .option('--poll-interval-ms <ms>', 'Polling interval while tailing')
-    .option('--tail-timeout-ms <ms>', 'Timeout while tailing')
-    .option('--force', 'Supersede any active runs for this play')
-    .option('--json', 'Emit JSON output')
-    .action(async (target, options, command) => {
-      const passthroughArgs = [...command.args];
-      const explicitTarget = options.file || options.name;
-      const targetIsInputFlag = typeof target === 'string' && target.startsWith('--');
-      const effectiveTarget = explicitTarget || targetIsInputFlag ? null : target;
-      if (
-        explicitTarget &&
-        typeof target === 'string' &&
-        !targetIsInputFlag &&
-        !passthroughArgs.includes(target)
-      ) {
-        passthroughArgs.push(target);
-      }
-      if (effectiveTarget && passthroughArgs[0] === effectiveTarget) {
-        passthroughArgs.shift();
-      }
-      process.exitCode = await handlePlayRun([
-        ...(effectiveTarget ? [effectiveTarget] : []),
-        ...(options.file ? ['--file', options.file] : []),
-        ...(options.name ? ['--name', options.name] : []),
-        ...(options.input ? ['--input', options.input] : []),
-        ...(options.live ? ['--live'] : []),
-        ...(options.latest ? ['--latest'] : []),
-        ...(options.revisionId ? ['--revision-id', options.revisionId] : []),
-        ...(options.out ? ['--out', options.out] : []),
-        ...(options.watch ? ['--watch'] : []),
-        ...(options.logs ? ['--logs'] : []),
-        ...(options.pollIntervalMs
-          ? ['--poll-interval-ms', options.pollIntervalMs]
-          : []),
-        ...(options.tailTimeoutMs
-          ? ['--tail-timeout-ms', options.tailTimeoutMs]
-          : []),
-        ...(options.force ? ['--force'] : []),
-        ...(options.json ? ['--json'] : []),
-        ...passthroughArgs,
-      ]);
-    });
-
-  play
-    .command('get <target>')
-    .description('Fetch full play details.')
-    .addHelpText(
-      'after',
-      `
-Notes:
-  Full-detail read for metadata, revisions/source fields, latest runs, sheet state,
-  customer DB state, and local file comparison. Use \`describe\` for the compact
-  contract and examples.
-
-Examples:
-  deepline plays get person-linkedin-to-email
-  deepline plays get person-linkedin-to-email --json | jq '.play.liveRevision'
-  deepline plays get prebuilt/name-and-domain-to-email-waterfall-batch --source > email-waterfall.play.ts
-  deepline plays get prebuilt/name-and-domain-to-email-waterfall-batch --source --out ./email-waterfall.play.ts
-`,
-    )
-    .option('--json', 'Emit JSON output. Also automatic when stdout is piped')
-    .option('--source', 'Print raw source code; combine with --out to write a file')
-    .option('--out <path>', 'Write source to a specific path')
-    .action(async (target, options) => {
-      process.exitCode = await handlePlayGet([
-        target,
-        ...(options.json ? ['--json'] : []),
-        ...(options.source ? ['--source'] : []),
-        ...(options.out ? ['--out', options.out] : []),
-      ]);
-    });
-
-  play
-    .command('list')
-    .description('List saved and prebuilt plays.')
-    .option('--json', 'Emit JSON output')
-    .action(async (options) => {
-      process.exitCode = await handlePlayList([
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-
-  play
-    .command('search <query>')
-    .description('Search saved and prebuilt plays.')
-    .option('--origin <origin>', 'Filter to prebuilt or owned plays')
-    .option('--compact', 'Emit compact schemas')
-    .option('--json', 'Emit JSON output. Also automatic when stdout is piped')
-    .action(async (query, options) => {
-      process.exitCode = await handlePlaySearch([
-        query,
-        ...(options.origin ? ['--origin', options.origin] : []),
-        ...(options.compact ? ['--compact'] : []),
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-
-  play
-    .command('describe <target>')
-    .description('Describe a play contract and how to run it.')
-    .addHelpText(
-      'after',
-      `
-Notes:
-  Compact contract read for schemas, aliases, examples, ownership, and the run command.
-  Use \`get\` when you need full metadata, revisions, source fields, or latest runs.
-
-Examples:
-  deepline plays describe person-linkedin-to-email
-  deepline plays describe person-linkedin-to-email --json
-`,
-    )
-    .option('--compact', 'Emit compact schemas')
-    .option('--json', 'Emit JSON output. Also automatic when stdout is piped')
-    .action(async (target, options) => {
-      process.exitCode = await handlePlayDescribe([
-        target,
-        ...(options.compact ? ['--compact'] : []),
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-
-  play
-    .command('runs')
-    .description('List runs for a named play.')
-    .option('--name <name>', 'Saved play name')
-    .option('--json', 'Emit JSON output')
-    .action(async (options) => {
-      process.exitCode = await handlePlayRuns([
-        ...(options.name ? ['--name', options.name] : []),
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-
-  play
-    .command('versions')
-    .description('List revisions for a named play.')
-    .option('--name <name>', 'Saved play name')
-    .option('--json', 'Emit JSON output')
-    .action(async (options) => {
-      process.exitCode = await handlePlayVersions([
-        ...(options.name ? ['--name', options.name] : []),
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-
-  play
-    .command('tail')
-    .description('Tail events for a play run.')
-    .option('--run-id <runId>', 'Run id to tail')
-    .option('--name <name>', 'Tail the latest run for a named play')
-    .option('--interval-ms <ms>', 'Polling interval while tailing')
-    .option('--logs', 'With --json, stream play logs to stderr while waiting')
-    .option('--json', 'Emit JSON output')
-    .action(async (options) => {
-      process.exitCode = await handlePlayTail([
-        ...(options.runId ? ['--run-id', options.runId] : []),
-        ...(options.name ? ['--name', options.name] : []),
-        ...(options.intervalMs ? ['--interval-ms', options.intervalMs] : []),
-        ...(options.logs ? ['--logs'] : []),
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-
-  play
-    .command('status')
-    .description('Show status for a play run.')
-    .option('--run-id <runId>', 'Run id to inspect')
-    .option('--name <name>', 'Inspect the latest run for a named play')
-    .option('--json', 'Emit JSON output')
-    .option('--full', 'Debug only: with --json, emit the raw status payload')
-    .action(async (options) => {
-      process.exitCode = await handlePlayStatus([
-        ...(options.runId ? ['--run-id', options.runId] : []),
-        ...(options.name ? ['--name', options.name] : []),
-        ...(options.json ? ['--json'] : []),
-        ...(options.full ? ['--full'] : []),
-      ]);
-    });
-
-  play
-    .command('export')
-    .description('Export a completed play run to CSV.')
-    .requiredOption('--run-id <runId>', 'Run id to export')
-    .requiredOption('--out <path>', 'Output CSV path')
-    .option('--json', 'Emit JSON output. Also automatic when stdout is piped')
-    .action(async (options) => {
-      process.exitCode = await handleRunExport([
-        options.runId,
-        '--out',
-        options.out,
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-
-  play
-    .command('stop')
-    .description('Stop a play run.')
-    .option('--run-id <runId>', 'Run id to stop')
-    .option('--reason <text>', 'Reason to include with the stop request')
-    .option('--json', 'Emit JSON output')
-    .action(async (options) => {
-      process.exitCode = await handlePlayStop([
-        ...(options.runId ? ['--run-id', options.runId] : []),
-        ...(options.reason ? ['--reason', options.reason] : []),
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-
-  play
-    .command('publish <target>')
-    .description('Bundle, validate, save, and publish a play.')
-    .option('--latest', 'Promote the newest saved revision')
-    .option('--revision-id <id>', 'Revision to promote')
-    .option('--json', 'Emit JSON output')
-    .action(async (target, options) => {
-      process.exitCode = await handlePlayPublish([
-        target,
-        ...(options.latest ? ['--latest'] : []),
-        ...(options.revisionId ? ['--revision-id', options.revisionId] : []),
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-
-  play
-    .command('delete <target>')
-    .description('Delete an org-owned play and its saved revisions/runs.')
-    .option('-y, --yes', 'Confirm deletion')
-    .option('--json', 'Emit JSON output. Also automatic when stdout is piped')
-    .action(async (target, options) => {
-      process.exitCode = await handlePlayDelete([
-        target,
-        ...(options.yes ? ['--yes'] : []),
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-
-  const runs = program
-    .command('runs')
-    .description('Inspect and export play runs.')
-    .addHelpText(
-      'after',
-      `
-Examples:
-  deepline runs status play/my-play/run/20260501t000000-000
-  deepline runs export play/my-play/run/20260501t000000-000 --out output.csv
-  deepline runs logs play/my-play/run/20260501t000000-000
-`,
-    );
-
-  runs
-    .command('status <runId>')
-    .description('Show compact status for a play run.')
-    .option('--json', 'Emit JSON output. Also automatic when stdout is piped')
-    .option('--full', 'Debug only: with --json, emit the raw status payload')
-    .action(async (runId, options) => {
-      process.exitCode = await handleRunStatus([
-        runId,
-        ...(options.json ? ['--json'] : []),
-        ...(options.full ? ['--full'] : []),
-      ]);
-    });
-
-  runs
-    .command('export <runId>')
-    .description('Export the completed row output for a play run to CSV.')
-    .requiredOption('--out <path>', 'Output CSV path')
-    .option('--json', 'Emit JSON output. Also automatic when stdout is piped')
-    .action(async (runId, options) => {
-      process.exitCode = await handleRunExport([
-        runId,
-        '--out',
-        options.out,
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-
-  runs
-    .command('logs <runId>')
-    .description('Print logs for a play run.')
-    .option('--json', 'Emit JSON output. Also automatic when stdout is piped')
-    .action(async (runId, options) => {
-      process.exitCode = await handleRunLogs([
-        runId,
-        ...(options.json ? ['--json'] : []),
-      ]);
-    });
-}