deepline 0.1.0 → 0.1.2

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

@@ -0,0 +1,3200 @@
+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 { recordCliTrace, traceCliSpan } from '../trace.js';
+import { argsWantJson } from '../utils.js';
+
+type PlayRunCommandOptions = {
+  target: { kind: 'file'; path: string } | { kind: 'name'; name: string };
+  csvPath: string | null;
+  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 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;
+  }
+  return (
+    target.includes('/') ||
+    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 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),
+        );
+
+  recordCliTrace({
+    phase: 'cli.start_stream_request',
+    playName: input.playName,
+  });
+  try {
+    let eventCount = 0;
+    for await (const event of input.client.startPlayRunStream(input.request, {
+      signal: controller.signal,
+    })) {
+      eventCount += 1;
+      if (eventCount === 1) {
+        recordCliTrace({
+          phase: 'cli.start_stream_first_event',
+          ms: Date.now() - startedAt,
+          playName: input.playName,
+          eventType: event.type,
+        });
+      }
+      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);
+        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) {
+        recordCliTrace({
+          phase: 'cli.start_stream_final_event',
+          ms: Date.now() - startedAt,
+          playName: input.playName,
+          runId: finalStatus.runId,
+          status: finalStatus.status,
+          eventCount,
+        });
+        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);
+        process.stderr.write(
+          `[play tail] transient status poll failed; retrying: ${message}\n`,
+        );
+        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`,
+    fullStatus: `deepline runs status ${runId} --json --full`,
+    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, 10) } : {}),
+    ...(billing ? { billing } : {}),
+    ...(status.run ? { run: status.run } : {}),
+    next: buildRunNextCommands(status.runId),
+  };
+}
+
+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
+      ? `, ${Object.entries(stat.top_values)
+          .slice(0, 3)
+          .map(([value, count]) => `${value}=${count}`)
+          .join(', ')}`
+      : '';
+    const sample =
+      stat.sample_value !== undefined
+        ? `, sample=${JSON.stringify(stat.sample_value)}`
+        : '';
+    lines.push(
+      `    ${column}: ${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 ? 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;
+}): 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}`);
+  }
+
+  console.log(lines.join('\n'));
+}
+
+function parsePlayRunOptions(args: string[]): PlayRunCommandOptions {
+  const usage =
+    "Usage: deepline plays run <play-name> [--input '{...}'] [--csv file.csv] [--live|--latest|--revision-id <id>] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force]\n" +
+    "       deepline plays run <play-file.ts> [--input '{...}'] [--csv file.csv] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force]\n" +
+    "       deepline plays run --file <play-file.ts> [--input '{...}'] [--csv file.csv] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force]\n" +
+    "       deepline plays run --name <name> [--input '{...}'] [--csv file.csv] [--live|--latest|--revision-id <id>] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--json]";
+  let filePath: string | null = null;
+  let playName: string | null = null;
+  let csvPath: 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 === '--csv' && args[index + 1]) {
+      csvPath = resolve(args[++index]!);
+      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('--')) {
+      throw new Error(`Unexpected flag: ${arg}\n${usage}`);
+    }
+    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! },
+    csvPath,
+    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);
+  recordCliTrace({
+    phase: 'cli.play_run_file_start',
+    playPath: absolutePlayPath,
+    watch: options.watch,
+    hasCsv: Boolean(options.csvPath),
+    force: options.force,
+  });
+  progress.phase('compiling play');
+  const readSourceStartedAt = Date.now();
+  const sourceCode = readFileSync(absolutePlayPath, 'utf-8');
+  recordCliTrace({
+    phase: 'cli.read_play_source',
+    ms: Date.now() - readSourceStartedAt,
+    bytes: sourceCode.length,
+    playPath: absolutePlayPath,
+  });
+  let graph: {
+    root: BundledPlayFileSuccess;
+    nodes: Map<string, BundledPlayFileSuccess>;
+  };
+  try {
+    graph = await traceCliSpan(
+      'cli.bundle_play_graph',
+      { playPath: absolutePlayPath },
+      () => collectBundledPlayGraph(absolutePlayPath),
+    );
+    await traceCliSpan(
+      'cli.compile_play_manifest',
+      { playPath: absolutePlayPath, nodeCount: graph.nodes.size },
+      () => 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 traceCliSpan(
+      'cli.publish_imported_plays',
+      { playName, nodeCount: graph.nodes.size },
+      () => 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 prepareFilesStartedAt = Date.now();
+  const packagedFileUploads = bundleResult.packagedFiles.map((file) =>
+    stageFile(file.logicalPath, file.absolutePath),
+  );
+  const inputFileUpload = options.csvPath
+    ? stageFile(basename(options.csvPath), options.csvPath)
+    : (packagedFileUploads[0] ?? null);
+  if (
+    options.csvPath &&
+    typeof runtimeInput.file !== 'string' &&
+    typeof runtimeInput.csv !== 'string'
+  ) {
+    runtimeInput.file = basename(options.csvPath);
+  }
+  recordCliTrace({
+    phase: 'cli.prepare_input_files',
+    ms: Date.now() - prepareFilesStartedAt,
+    playName,
+    packagedFileCount: packagedFileUploads.length,
+    hasInputFile: Boolean(inputFileUpload),
+  });
+
+  const startRequest = {
+    name: playName,
+    sourceCode: bundleResult.sourceCode,
+    runtimeArtifact: bundleResult.artifact,
+    compilerManifest: requireCompilerManifest(bundleResult),
+    inputFileUpload,
+    packagedFileUploads,
+    ...(Object.keys(runtimeInput).length > 0 ? { input: runtimeInput } : {}),
+    ...(options.force ? { force: true } : {}),
+  };
+
+  if (options.watch) {
+    progress.phase('starting run');
+    const finalStatus = await traceCliSpan(
+      'cli.start_and_watch',
+      { playName },
+      () =>
+        startAndWaitForPlayCompletionByStream({
+          client,
+          request: startRequest,
+          playName,
+          jsonOutput: options.jsonOutput,
+          emitLogs: options.emitLogs,
+          waitTimeoutMs: options.waitTimeoutMs,
+          progress,
+        }),
+    );
+    const exportStartedAt = Date.now();
+    const exportedPath = exportPlayStatusRows(finalStatus, options.outPath);
+    recordCliTrace({
+      phase: 'cli.export_rows',
+      ms: Date.now() - exportStartedAt,
+      playName,
+      exported: Boolean(exportedPath),
+    });
+    if (finalStatus.status === 'completed') {
+      progress.complete();
+    } else {
+      progress.fail();
+    }
+    recordCliTrace({
+      phase: 'cli.write_play_result',
+      playName,
+      status: finalStatus.status,
+      runId: finalStatus.runId,
+    });
+    writePlayResult(finalStatus, options.jsonOutput, { exportedPath });
+    return finalStatus.status === 'completed' ? 0 : 1;
+  }
+
+  progress.phase('starting run');
+  const started = await traceCliSpan(
+    'cli.start_run',
+    { playName },
+    () => client.startPlayRun(startRequest),
+  );
+  const fallbackDashboardUrl = buildPlayDashboardUrl(client.baseUrl, playName);
+  const dashboardUrl = started.dashboardUrl ?? fallbackDashboardUrl;
+  progress.phase(`loading play on ${dashboardUrl}`);
+  progress.complete();
+
+  writeStartedPlayRun({
+    runId: started.workflowId,
+    playName,
+    status: started.status,
+    statusUrl: started.statusUrl,
+    dashboardUrl,
+    jsonOutput: options.jsonOutput,
+  });
+  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);
+  let stagedInputFile: PlayStagedFileRef | null = null;
+
+  progress.phase('loading play definition');
+  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,
+  });
+
+  if (options.csvPath) {
+    progress.phase('staging input file');
+    const [staged] = await client.stagePlayFiles([
+      stageFile(basename(options.csvPath), options.csvPath),
+    ]);
+    stagedInputFile = staged ?? null;
+  }
+
+  const runtimeInput = options.input ? { ...options.input } : {};
+
+  const startRequest = {
+    name: options.target.name,
+    ...(selectedRevisionId ? { revisionId: selectedRevisionId } : {}),
+    ...(Object.keys(runtimeInput).length > 0 ? { input: runtimeInput } : {}),
+    ...(stagedInputFile ? { inputFile: stagedInputFile } : {}),
+    ...(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 fallbackDashboardUrl = buildPlayDashboardUrl(
+    client.baseUrl,
+    options.target.name,
+  );
+  const dashboardUrl = started.dashboardUrl ?? fallbackDashboardUrl;
+  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,
+    jsonOutput: options.jsonOutput,
+  });
+  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 jsonOutput = argsWantJson(args);
+  const sourceOutput = args.includes('--source');
+  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 =
+    sourceOutput || 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;
+  }
+
+  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}`);
+    }
+  }
+  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 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.')
+    .addHelpText(
+      'after',
+      `
+Notes:
+  Local play files are bundled locally, then validated and executed in Deepline cloud.
+  Named plays run the stored live cloud revision.
+  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('--csv <path>', 'Attach a CSV file')
+    .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) => {
+      process.exitCode = await handlePlayRun([
+        ...(target ? [target] : []),
+        ...(options.file ? ['--file', options.file] : []),
+        ...(options.name ? ['--name', options.name] : []),
+        ...(options.csv ? ['--csv', options.csv] : []),
+        ...(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'] : []),
+      ]);
+    });
+
+  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'
+`,
+    )
+    .option('--json', 'Emit JSON output. Also automatic when stdout is piped')
+    .addOption(
+      new Option('--source', 'Materialize or print the source code').hideHelp(),
+    )
+    .addOption(
+      new Option('--out <path>', 'Write source to a specific path').hideHelp(),
+    )
+    .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', 'With --json, emit the full 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'] : []),
+      ]);
+    });
+
+  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', 'With --json, emit the full 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'] : []),
+      ]);
+    });
+}