deepline 0.1.90 → 0.1.93

package/dist/cli/index.mjs

@@ -206,10 +206,10 @@ import { join as join2 } from "path";
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.90",
+  version: "0.1.93",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.90",
+    latest: "0.1.93",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -564,6 +564,807 @@ function sleep(ms) {
   return new Promise((resolve14) => setTimeout(resolve14, ms));
 }
 
+// src/stream-reconnect.ts
+var STREAM_RECONNECT_BASE_DELAY_MS = 500;
+var STREAM_RECONNECT_MAX_DELAY_MS = 15e3;
+var STREAM_HEALTHY_CONNECTION_MS = 3e4;
+function streamReconnectDelayMs(attempt) {
+  const cappedExponentialMs = Math.min(
+    STREAM_RECONNECT_MAX_DELAY_MS,
+    STREAM_RECONNECT_BASE_DELAY_MS * 2 ** Math.max(0, attempt)
+  );
+  return Math.max(1, Math.floor(Math.random() * (cappedExponentialMs + 1)));
+}
+function isTransientPlayStreamError(error) {
+  if (error instanceof DeeplineError && typeof error.statusCode === "number") {
+    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
+  );
+}
+
+// ../shared_libs/play-runtime/live-events.ts
+function resolveTimingWindow(input2) {
+  const startedAt = typeof input2.startedAt === "number" && Number.isFinite(input2.startedAt) ? input2.startedAt : null;
+  const completedAt = typeof input2.completedAt === "number" && Number.isFinite(input2.completedAt) ? input2.completedAt : null;
+  const updatedAt = typeof input2.updatedAt === "number" && Number.isFinite(input2.updatedAt) ? input2.updatedAt : null;
+  return {
+    startedAt,
+    completedAt,
+    updatedAt
+  };
+}
+
+// ../shared_libs/play-runtime/run-ledger.ts
+var LOG_TAIL_LIMIT = 100;
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function optionalFiniteNumber(value) {
+  const normalized = finiteNumber(value);
+  return normalized === null ? void 0 : normalized;
+}
+function optionalString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function optionalNullableString(value) {
+  if (value === null) return null;
+  return optionalString(value);
+}
+function normalizePlayRunLedgerStatus(value) {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  switch (normalized) {
+    case "queued":
+    case "pending":
+      return "queued";
+    case "running":
+    case "started":
+      return "running";
+    case "waiting":
+      return "waiting";
+    case "completed":
+    case "complete":
+    case "succeeded":
+      return "completed";
+    case "failed":
+    case "error":
+      return "failed";
+    case "cancelled":
+    case "canceled":
+      return "cancelled";
+    case "terminated":
+      return "terminated";
+    case "timed_out":
+    case "timeout":
+      return "timed_out";
+    default:
+      return "unknown";
+  }
+}
+function createEmptyPlayRunLedgerSnapshot(input2) {
+  const status = normalizePlayRunLedgerStatus(input2.status ?? "unknown");
+  const startedAt = finiteNumber(input2.startedAt) ?? null;
+  const finishedAt = finiteNumber(input2.finishedAt) ?? null;
+  return {
+    runId: input2.runId,
+    playName: input2.playName ?? null,
+    status,
+    error: optionalNullableString(input2.error) ?? null,
+    createdAt: finiteNumber(input2.createdAt) ?? null,
+    startedAt,
+    updatedAt: finiteNumber(input2.updatedAt) ?? finishedAt ?? startedAt ?? finiteNumber(input2.createdAt) ?? null,
+    finishedAt,
+    durationMs: startedAt !== null && finishedAt !== null ? Math.max(0, finishedAt - startedAt) : null,
+    orderedStepIds: [],
+    stepsById: {},
+    logTail: [],
+    totalLogCount: 0,
+    logsTruncated: false,
+    activeStepId: null,
+    activeArtifactTableNamespace: null,
+    resultTableNamespace: null
+  };
+}
+function normalizePlayRunLedgerSnapshot(value, fallback) {
+  if (!isRecord(value)) {
+    return createEmptyPlayRunLedgerSnapshot(fallback);
+  }
+  const orderedStepIds = Array.isArray(value.orderedStepIds) ? value.orderedStepIds.filter(
+    (entry) => typeof entry === "string" && Boolean(entry.trim())
+  ) : [];
+  const rawSteps = isRecord(value.stepsById) ? value.stepsById : {};
+  const stepsById = {};
+  for (const [stepId, rawStep] of Object.entries(rawSteps)) {
+    if (!stepId.trim() || !isRecord(rawStep)) continue;
+    const rawStatus = normalizeStepStatus(rawStep.status);
+    if (!rawStatus) continue;
+    const completedAt = finiteNumber(rawStep.completedAt);
+    const status = rawStatus === "running" && completedAt !== null ? "completed" : rawStatus;
+    const rawProgress = isRecord(rawStep.progress) ? rawStep.progress : null;
+    stepsById[stepId] = {
+      stepId,
+      label: optionalString(rawStep.label),
+      kind: optionalString(rawStep.kind),
+      status,
+      artifactTableNamespace: optionalNullableString(
+        rawStep.artifactTableNamespace
+      ),
+      startedAt: finiteNumber(rawStep.startedAt),
+      completedAt,
+      updatedAt: finiteNumber(rawStep.updatedAt),
+      progress: rawProgress ? normalizeStepProgress(rawProgress) : null
+    };
+  }
+  const createdAt = finiteNumber(value.createdAt) ?? fallback.createdAt ?? null;
+  const startedAt = finiteNumber(value.startedAt) ?? fallback.startedAt ?? null;
+  const finishedAt = finiteNumber(value.finishedAt) ?? fallback.finishedAt ?? null;
+  const updatedAt = finiteNumber(value.updatedAt) ?? fallback.updatedAt ?? finishedAt ?? startedAt ?? createdAt ?? null;
+  const error = Object.prototype.hasOwnProperty.call(value, "error") ? optionalNullableString(value.error) ?? null : fallback.error ?? null;
+  const rawTail = Array.isArray(value.logTail) ? value.logTail : value.logs;
+  const logTail = Array.isArray(rawTail) ? rawTail.filter((line) => typeof line === "string") : [];
+  return {
+    runId: optionalString(value.runId) ?? fallback.runId,
+    playName: optionalNullableString(value.playName) ?? fallback.playName ?? null,
+    status: normalizePlayRunLedgerStatus(value.status ?? fallback.status),
+    error,
+    createdAt,
+    startedAt,
+    updatedAt,
+    finishedAt,
+    durationMs: startedAt !== null && finishedAt !== null ? Math.max(0, finishedAt - startedAt) : finiteNumber(value.durationMs),
+    orderedStepIds: orderedStepIds.filter((stepId) => stepsById[stepId]),
+    stepsById,
+    logTail: logTail.slice(-LOG_TAIL_LIMIT),
+    // Snapshots persisted before totalLogCount existed only know the retained
+    // tail, so the best lower bound for the cumulative count is the tail size.
+    totalLogCount: Math.max(
+      finiteNumber(value.totalLogCount) ?? logTail.length,
+      logTail.length
+    ),
+    logsTruncated: value.logsTruncated === true,
+    activeStepId: optionalNullableString(value.activeStepId),
+    activeArtifactTableNamespace: optionalNullableString(
+      value.activeArtifactTableNamespace
+    ),
+    resultTableNamespace: optionalNullableString(value.resultTableNamespace),
+    resultSummary: value.resultSummary,
+    result: value.result
+  };
+}
+function normalizeStepStatus(value) {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  if (normalized === "running" || normalized === "completed" || normalized === "failed" || normalized === "skipped") {
+    return normalized;
+  }
+  return null;
+}
+function normalizeStepProgress(value) {
+  return {
+    ...optionalFiniteNumber(value.completed) !== void 0 ? { completed: optionalFiniteNumber(value.completed) } : {},
+    ...optionalFiniteNumber(value.total) !== void 0 ? { total: optionalFiniteNumber(value.total) } : {},
+    ...optionalFiniteNumber(value.failed) !== void 0 ? { failed: optionalFiniteNumber(value.failed) } : {},
+    ...optionalString(value.message) ? { message: optionalString(value.message) } : {},
+    ...optionalNullableString(value.artifactTableNamespace) !== void 0 ? {
+      artifactTableNamespace: optionalNullableString(
+        value.artifactTableNamespace
+      )
+    } : {},
+    ...finiteNumber(value.updatedAt) !== null ? { updatedAt: finiteNumber(value.updatedAt) } : {}
+  };
+}
+
+// ../shared_libs/play-runtime/run-snapshot-stream.ts
+function normalizePlayRunLiveStatus(value) {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  switch (normalized) {
+    case "queued":
+    case "pending":
+      return "running";
+    case "running":
+    case "started":
+      return "running";
+    case "completed":
+    case "complete":
+    case "succeeded":
+      return "completed";
+    case "failed":
+    case "error":
+      return "failed";
+    case "cancelled":
+    case "canceled":
+      return "cancelled";
+    case "terminated":
+      return "terminated";
+    case "timed_out":
+    case "timeout":
+      return "timed_out";
+    default:
+      return "unknown";
+  }
+}
+function isTerminalPlayRunLiveStatus(status) {
+  return status === "completed" || status === "failed" || status === "cancelled" || status === "terminated" || status === "timed_out";
+}
+function buildSnapshotFromLedger(snapshot) {
+  const nodeStates = snapshot.orderedStepIds.map((stepId) => snapshot.stepsById[stepId]).filter((step) => Boolean(step)).map((step) => ({
+    nodeId: step.stepId,
+    status: step.status,
+    artifactTableNamespace: step.artifactTableNamespace ?? null,
+    progress: step.progress ? {
+      completed: step.progress.completed,
+      total: step.progress.total,
+      failed: step.progress.failed,
+      message: step.progress.message,
+      artifactTableNamespace: step.progress.artifactTableNamespace ?? step.artifactTableNamespace ?? null,
+      startedAt: step.startedAt ?? null,
+      completedAt: step.completedAt ?? null,
+      updatedAt: step.progress.updatedAt ?? step.updatedAt ?? null
+    } : null,
+    startedAt: step.startedAt ?? null,
+    completedAt: step.completedAt ?? null,
+    updatedAt: step.updatedAt ?? null
+  }));
+  return {
+    runId: snapshot.runId,
+    status: normalizePlayRunLiveStatus(snapshot.status),
+    updatedAt: snapshot.updatedAt ?? snapshot.finishedAt ?? snapshot.startedAt ?? null,
+    logs: snapshot.logTail,
+    totalLogCount: snapshot.totalLogCount,
+    ...snapshot.logsTruncated ? { logsTruncated: true } : {},
+    activeArtifactTableNamespace: snapshot.activeArtifactTableNamespace ?? null,
+    resultTableNamespace: snapshot.resultTableNamespace ?? null,
+    nodeStates,
+    activeNodeId: snapshot.activeStepId ?? null
+  };
+}
+function buildPlayRunStatusSnapshot(input2) {
+  const ledgerSnapshot = normalizePlayRunLedgerSnapshot(input2.run.runSnapshot, {
+    runId: input2.run.workflowId,
+    playName: input2.run.name ?? null,
+    status: input2.run.status,
+    createdAt: input2.run.createdAt ?? null,
+    startedAt: input2.run.startedAt ?? null,
+    updatedAt: input2.run.updatedAt ?? null,
+    finishedAt: input2.run.finishedAt ?? null
+  });
+  return buildSnapshotFromLedger(ledgerSnapshot);
+}
+function makeRunStreamEvent(input2) {
+  return {
+    ...input2,
+    scope: "play",
+    at: input2.at ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+var EMPTY_PLAY_RUN_STREAM_DIFF_STATE = {
+  runSignature: "",
+  snapshotSignature: "",
+  stepStatusSignature: "",
+  stepProgressSignature: "",
+  lastLogSeq: 0
+};
+function getSnapshotCursor(snapshot) {
+  return String(snapshot.updatedAt ?? Date.now());
+}
+function getRunSignature(snapshot) {
+  return [snapshot.runId, snapshot.status, snapshot.updatedAt ?? 0].join(":");
+}
+function getStepStatusSignature(snapshot) {
+  return snapshot.nodeStates.map(
+    (state) => [
+      state.nodeId,
+      state.status,
+      state.artifactTableNamespace ?? "",
+      state.startedAt ?? "",
+      state.completedAt ?? "",
+      state.progress?.startedAt ?? "",
+      state.progress?.completedAt ?? "",
+      state.updatedAt ?? "",
+      state.progress?.updatedAt ?? ""
+    ].join(":")
+  ).join("|");
+}
+function getStepProgressSignature(snapshot) {
+  return snapshot.nodeStates.map(
+    (state) => [
+      state.nodeId,
+      state.progress?.completed ?? "",
+      state.progress?.total ?? "",
+      state.progress?.failed ?? "",
+      state.progress?.artifactTableNamespace ?? "",
+      state.progress?.startedAt ?? "",
+      state.progress?.completedAt ?? "",
+      state.progress?.updatedAt ?? "",
+      state.progress?.message ?? ""
+    ].join(":")
+  ).join("|");
+}
+function getSnapshotSignature(snapshot) {
+  return JSON.stringify(snapshot);
+}
+function resolvePlayRunLogGap(snapshot, lastLogSeq) {
+  if (snapshot.totalLogCount <= lastLogSeq) {
+    return null;
+  }
+  const tailFirstSeq = snapshot.totalLogCount - snapshot.logs.length + 1;
+  if (lastLogSeq + 1 >= tailFirstSeq) {
+    return null;
+  }
+  return {
+    missingCount: tailFirstSeq - 1 - lastLogSeq,
+    tailFirstSeq
+  };
+}
+function diffLogLines(input2) {
+  const { logs, totalLogCount } = input2.snapshot;
+  if (totalLogCount <= input2.lastLogSeq) {
+    return { lines: [], lastLogSeq: input2.lastLogSeq, firstSeq: null };
+  }
+  const tailFirstSeq = totalLogCount - logs.length + 1;
+  if (input2.lastLogSeq + 1 >= tailFirstSeq) {
+    return {
+      lines: logs.slice(input2.lastLogSeq + 1 - tailFirstSeq),
+      lastLogSeq: totalLogCount,
+      firstSeq: input2.lastLogSeq + 1
+    };
+  }
+  const missingCount = tailFirstSeq - 1 - input2.lastLogSeq;
+  return {
+    lines: [
+      `[stream] ${missingCount} log lines not retained in the live window; full logs via runs logs`,
+      ...logs
+    ],
+    lastLogSeq: totalLogCount,
+    firstSeq: null
+  };
+}
+function diffPlayRunStreamEvents(input2) {
+  const { snapshot, streamId, previous } = input2;
+  const cursor = getSnapshotCursor(snapshot);
+  const logDiff = diffLogLines({
+    snapshot,
+    lastLogSeq: previous.lastLogSeq
+  });
+  const next = {
+    runSignature: getRunSignature(snapshot),
+    stepStatusSignature: getStepStatusSignature(snapshot),
+    stepProgressSignature: getStepProgressSignature(snapshot),
+    snapshotSignature: getSnapshotSignature(snapshot),
+    lastLogSeq: logDiff.lastLogSeq
+  };
+  const events = [];
+  if (next.stepStatusSignature !== previous.stepStatusSignature) {
+    for (const state of snapshot.nodeStates) {
+      if (state.status === "idle") {
+        continue;
+      }
+      const persistedStartedAt = state.startedAt ?? state.progress?.startedAt ?? null;
+      const persistedCompletedAt = state.completedAt ?? state.progress?.completedAt ?? null;
+      events.push(
+        makeRunStreamEvent({
+          cursor,
+          streamId,
+          type: "play.step.status",
+          payload: {
+            runId: snapshot.runId,
+            stepId: state.nodeId,
+            status: state.status,
+            artifactTableNamespace: state.artifactTableNamespace ?? null,
+            ...resolveTimingWindow({
+              startedAt: persistedStartedAt,
+              completedAt: persistedCompletedAt,
+              updatedAt: state.updatedAt ?? state.progress?.updatedAt ?? snapshot.updatedAt ?? null
+            })
+          }
+        })
+      );
+    }
+  }
+  if (next.stepProgressSignature !== previous.stepProgressSignature) {
+    for (const state of snapshot.nodeStates) {
+      if (!state.progress) {
+        continue;
+      }
+      events.push(
+        makeRunStreamEvent({
+          cursor: String(
+            state.progress.updatedAt ?? snapshot.updatedAt ?? Date.now()
+          ),
+          streamId,
+          type: "play.step.progress",
+          payload: {
+            runId: snapshot.runId,
+            stepId: state.nodeId,
+            completed: state.progress.completed,
+            total: state.progress.total,
+            failed: state.progress.failed,
+            message: state.progress.message,
+            artifactTableNamespace: state.progress.artifactTableNamespace ?? state.artifactTableNamespace ?? null,
+            ...resolveTimingWindow({
+              startedAt: state.startedAt ?? state.progress.startedAt ?? null,
+              completedAt: state.completedAt ?? state.progress.completedAt ?? null,
+              updatedAt: state.progress.updatedAt ?? snapshot.updatedAt ?? null
+            })
+          }
+        })
+      );
+    }
+  }
+  if (logDiff.lines.length > 0) {
+    events.push(
+      makeRunStreamEvent({
+        cursor,
+        streamId,
+        type: "play.run.log",
+        payload: {
+          runId: snapshot.runId,
+          lines: logDiff.lines,
+          source: "worker",
+          ...logDiff.firstSeq !== null ? { firstSeq: logDiff.firstSeq } : {},
+          totalLogCount: snapshot.totalLogCount
+        }
+      })
+    );
+  }
+  if (next.snapshotSignature !== previous.snapshotSignature) {
+    const enrichedNodeStates = snapshot.nodeStates.map((state) => {
+      const timing = resolveTimingWindow({
+        startedAt: state.startedAt ?? state.progress?.startedAt ?? null,
+        completedAt: state.completedAt ?? state.progress?.completedAt ?? null,
+        updatedAt: state.updatedAt ?? state.progress?.updatedAt ?? snapshot.updatedAt ?? null
+      });
+      return {
+        ...state,
+        ...timing,
+        progress: state.progress ? {
+          ...state.progress,
+          ...resolveTimingWindow({
+            startedAt: state.progress.startedAt ?? state.startedAt ?? null,
+            completedAt: state.progress.completedAt ?? state.completedAt ?? null,
+            updatedAt: state.progress.updatedAt ?? state.updatedAt ?? snapshot.updatedAt ?? null
+          })
+        } : state.progress
+      };
+    });
+    events.push(
+      makeRunStreamEvent({
+        cursor,
+        streamId,
+        type: "play.run.snapshot",
+        payload: { ...snapshot, nodeStates: enrichedNodeStates }
+      })
+    );
+  }
+  if (next.runSignature !== previous.runSignature) {
+    events.push(
+      makeRunStreamEvent({
+        cursor,
+        streamId,
+        type: "play.run.status",
+        payload: {
+          runId: snapshot.runId,
+          status: snapshot.status,
+          updatedAt: snapshot.updatedAt
+        }
+      })
+    );
+  }
+  return { events, next };
+}
+
+// src/runs/observe-transport.ts
+var RunObserveTransportUnavailableError = class extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "RunObserveTransportUnavailableError";
+  }
+  reason;
+};
+var OBSERVE_BOOTSTRAP_TIMEOUT_MS = 1e4;
+var OBSERVE_RECONNECT_NOTICE_MS = 1e4;
+var OBSERVE_STALE_WARNING_MS = 12e4;
+var OBSERVE_WATCHDOG_TICK_MS = 5e3;
+var GRANT_REFRESH_MARGIN_MS = 5 * 6e4;
+var BACKFILL_PAGE_LIMIT = 1e3;
+var BACKFILL_MAX_PAGES = 30;
+var OBSERVER_SNAPSHOT_QUERY = "runObservers:getPlayRunSnapshotForObserver";
+var OBSERVER_LOG_PAGE_QUERY = "runObservers:getRunLogPageForObserver";
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function mintRunObserveGrant(http, runId) {
+  let response;
+  try {
+    response = await http.post(
+      `/api/v2/runs/${encodeURIComponent(runId)}/observe-grant`,
+      {}
+    );
+  } catch (error) {
+    if (error instanceof DeeplineError) {
+      if (error.statusCode === 401 || error.statusCode === 403) {
+        throw error;
+      }
+      throw new RunObserveTransportUnavailableError(
+        `observe-grant endpoint unavailable (${error.statusCode ?? "network"}): ${error.message}`,
+        "grant_endpoint_unavailable"
+      );
+    }
+    throw new RunObserveTransportUnavailableError(
+      `observe-grant request failed: ${errorText(error)}`,
+      "grant_request_failed"
+    );
+  }
+  const grant = response;
+  if (!grant || typeof grant.convexUrl !== "string" || !grant.convexUrl.trim() || typeof grant.token !== "string" || !grant.token.trim() || typeof grant.expiresAt !== "number") {
+    throw new RunObserveTransportUnavailableError(
+      "observe-grant endpoint returned an invalid grant payload.",
+      "grant_payload_invalid"
+    );
+  }
+  return grant;
+}
+async function backfillLogGap(input2) {
+  const lines = [];
+  let cursor = input2.lastLogSeq;
+  for (let page = 0; page < BACKFILL_MAX_PAGES; page += 1) {
+    if (cursor >= input2.tailFirstSeq - 1) {
+      break;
+    }
+    let logPage;
+    try {
+      logPage = await input2.queryLogPage(
+        cursor,
+        Math.min(BACKFILL_PAGE_LIMIT, input2.tailFirstSeq - 1 - cursor)
+      );
+    } catch {
+      return null;
+    }
+    const entries = (logPage?.entries ?? []).filter(
+      (entry) => entry.seq > cursor && entry.seq < input2.tailFirstSeq
+    );
+    if (entries.length === 0) {
+      break;
+    }
+    for (const entry of entries) {
+      if (entry.seq !== cursor + 1) {
+        return null;
+      }
+      lines.push(entry.line);
+      cursor = entry.seq;
+    }
+  }
+  if (cursor < input2.tailFirstSeq - 1) {
+    return null;
+  }
+  return lines;
+}
+async function* observeRunEvents(options) {
+  const { http, runId } = options;
+  let grant = await mintRunObserveGrant(http, runId);
+  let convexBrowser;
+  let convexServer;
+  try {
+    convexBrowser = await import("convex/browser");
+    convexServer = await import("convex/server");
+  } catch (error) {
+    throw new RunObserveTransportUnavailableError(
+      `convex client module unavailable: ${errorText(error)}`,
+      "convex_module_unavailable"
+    );
+  }
+  let webSocketConstructor;
+  if (typeof WebSocket === "undefined") {
+    try {
+      const wsModuleName = "ws";
+      const ws = await import(wsModuleName);
+      webSocketConstructor = ws.default;
+    } catch (error) {
+      throw new RunObserveTransportUnavailableError(
+        `no WebSocket implementation available: ${errorText(error)}`,
+        "websocket_unavailable"
+      );
+    }
+  }
+  const snapshotQuery = convexServer.makeFunctionReference(
+    OBSERVER_SNAPSHOT_QUERY
+  );
+  const logPageQuery = convexServer.makeFunctionReference(
+    OBSERVER_LOG_PAGE_QUERY
+  );
+  const client = new convexBrowser.ConvexClient(grant.convexUrl, {
+    ...webSocketConstructor ? { webSocketConstructor } : {},
+    unsavedChangesWarning: false
+  });
+  const queue = [];
+  let wake = null;
+  const push = (item) => {
+    queue.push(item);
+    wake?.();
+    wake = null;
+  };
+  let lastForcedRefreshAt = 0;
+  client.setAuth(async ({ forceRefreshToken }) => {
+    const now = Date.now();
+    if (!forceRefreshToken && grant.expiresAt - now > GRANT_REFRESH_MARGIN_MS) {
+      return grant.token;
+    }
+    if (forceRefreshToken && now - lastForcedRefreshAt < 5e3) {
+      push({
+        kind: "error",
+        error: new DeeplineError(
+          `Run observe grant for ${runId} was rejected after a re-mint. The server and Convex deployment disagree on the grant issuer/JWKS.`,
+          401,
+          "RUN_OBSERVE_GRANT_REJECTED"
+        )
+      });
+      return null;
+    }
+    if (forceRefreshToken) {
+      lastForcedRefreshAt = now;
+    }
+    try {
+      grant = await mintRunObserveGrant(http, runId);
+      return grant.token;
+    } catch (error) {
+      push({ kind: "error", error });
+      return null;
+    }
+  });
+  const unsubscribe = client.onUpdate(
+    snapshotQuery,
+    { workflowId: runId },
+    (run) => push({ kind: "run", run: run ?? null }),
+    (error) => push({ kind: "error", error })
+  );
+  let lastUpdateAt = Date.now();
+  let lastStatusTerminal = false;
+  let disconnectedSince = null;
+  let warnedReconnecting = false;
+  let warnedStale = false;
+  const watchdog = setInterval(() => {
+    const now = Date.now();
+    try {
+      const connectionState = client.connectionState();
+      if (connectionState.isWebSocketConnected) {
+        disconnectedSince = null;
+        warnedReconnecting = false;
+      } else {
+        disconnectedSince ??= now;
+        if (!warnedReconnecting && now - disconnectedSince >= OBSERVE_RECONNECT_NOTICE_MS) {
+          warnedReconnecting = true;
+          options.onNotice?.(
+            `[observe] connection lost; reconnecting to live run ${runId}\u2026`
+          );
+        }
+      }
+    } catch {
+    }
+    if (!lastStatusTerminal && !warnedStale && now - lastUpdateAt >= OBSERVE_STALE_WARNING_MS) {
+      warnedStale = true;
+      options.onNotice?.(
+        `[observe] no live updates for ${Math.round((now - lastUpdateAt) / 1e3)}s; run ${runId} may be stalled (status checks continue)`
+      );
+    }
+  }, OBSERVE_WATCHDOG_TICK_MS);
+  watchdog.unref?.();
+  const abortListener = () => push({
+    kind: "error",
+    error: new DeeplineError(
+      "Run observation aborted.",
+      void 0,
+      "ABORTED"
+    )
+  });
+  options.signal?.addEventListener("abort", abortListener, { once: true });
+  let diffState = EMPTY_PLAY_RUN_STREAM_DIFF_STATE;
+  const streamId = ["observe", runId].join(":");
+  let sawFirstSnapshot = false;
+  try {
+    for (; ; ) {
+      if (queue.length === 0) {
+        const waitForItem = new Promise((resolve14) => {
+          wake = resolve14;
+        });
+        if (!sawFirstSnapshot) {
+          const timedOut = await Promise.race([
+            waitForItem.then(() => false),
+            new Promise(
+              (resolve14) => setTimeout(() => resolve14(true), OBSERVE_BOOTSTRAP_TIMEOUT_MS)
+            )
+          ]);
+          if (timedOut && queue.length === 0) {
+            throw new RunObserveTransportUnavailableError(
+              `no snapshot from Convex at ${grant.convexUrl} within ${OBSERVE_BOOTSTRAP_TIMEOUT_MS}ms`,
+              "convex_unreachable"
+            );
+          }
+        } else {
+          await waitForItem;
+        }
+        continue;
+      }
+      const item = queue.shift();
+      if (item.kind === "error") {
+        if (options.signal?.aborted) {
+          return;
+        }
+        throw item.error;
+      }
+      sawFirstSnapshot = true;
+      lastUpdateAt = Date.now();
+      warnedStale = false;
+      if (item.run === null) {
+        throw new DeeplineError(
+          `Run ${runId} was not found (or is not visible to this grant).`,
+          404,
+          "RUN_NOT_FOUND"
+        );
+      }
+      const snapshot = buildPlayRunStatusSnapshot({ run: item.run });
+      lastStatusTerminal = isTerminalPlayRunLiveStatus(snapshot.status);
+      const gap = resolvePlayRunLogGap(snapshot, diffState.lastLogSeq);
+      if (gap && diffState.lastLogSeq > 0) {
+        const backfilled = await backfillLogGap({
+          queryLogPage: (afterSeq, limit) => client.query(logPageQuery, {
+            workflowId: runId,
+            afterSeq,
+            limit
+          }),
+          lastLogSeq: diffState.lastLogSeq,
+          tailFirstSeq: gap.tailFirstSeq
+        });
+        if (backfilled && backfilled.length > 0) {
+          yield {
+            cursor: String(snapshot.updatedAt ?? Date.now()),
+            streamId,
+            scope: "play",
+            type: "play.run.log",
+            at: (/* @__PURE__ */ new Date()).toISOString(),
+            payload: {
+              runId: snapshot.runId,
+              lines: backfilled,
+              source: "worker",
+              firstSeq: diffState.lastLogSeq + 1,
+              totalLogCount: snapshot.totalLogCount
+            }
+          };
+          diffState = { ...diffState, lastLogSeq: gap.tailFirstSeq - 1 };
+        }
+      }
+      const { events, next } = diffPlayRunStreamEvents({
+        streamId,
+        snapshot,
+        previous: diffState
+      });
+      diffState = next;
+      const ordered = [
+        ...events.filter((event) => event.type === "play.run.snapshot"),
+        ...events.filter((event) => event.type !== "play.run.snapshot")
+      ];
+      for (const event of ordered) {
+        yield event;
+      }
+      if (lastStatusTerminal) {
+        return;
+      }
+    }
+  } finally {
+    clearInterval(watchdog);
+    options.signal?.removeEventListener("abort", abortListener);
+    try {
+      unsubscribe();
+    } catch {
+    }
+    await client.close().catch(() => void 0);
+  }
+}
+
 // src/client.ts
 var TERMINAL_PLAY_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
 var INCLUDE_TOOL_METADATA_HEADER = "x-deepline-include-tool-metadata";
@@ -582,7 +1383,8 @@ function isTransientCompileManifestError(error) {
     message
   );
 }
-function isRecord(value) {
+var RUN_LOGS_PAGE_LIMIT = 1e3;
+function isRecord2(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function isPrebuiltPlayDescription(play) {
@@ -652,10 +1454,31 @@ function normalizeLiveStatus(value) {
   }
   return null;
 }
+function appendPlayLiveLogLines(state, payload) {
+  const lines = readStringArray(payload.lines);
+  if (lines.length === 0) {
+    return;
+  }
+  const firstSeq = typeof payload.firstSeq === "number" && Number.isFinite(payload.firstSeq) && payload.firstSeq >= 1 ? Math.trunc(payload.firstSeq) : null;
+  if (firstSeq === null) {
+    state.logs.push(...lines);
+    const totalLogCount = typeof payload.totalLogCount === "number" && Number.isFinite(payload.totalLogCount) ? Math.trunc(payload.totalLogCount) : null;
+    if (totalLogCount !== null) {
+      state.lastLogSeq = Math.max(state.lastLogSeq, totalLogCount);
+    }
+    return;
+  }
+  const skip = Math.max(0, state.lastLogSeq + 1 - firstSeq);
+  if (skip >= lines.length) {
+    return;
+  }
+  state.logs.push(...lines.slice(skip));
+  state.lastLogSeq = Math.max(state.lastLogSeq, firstSeq + lines.length - 1);
+}
 function updatePlayLiveStatusState(state, event) {
   const payload = getPlayLiveEventPayload(event);
   if (event.type === "play.run.log") {
-    state.logs.push(...readStringArray(payload.lines));
+    appendPlayLiveLogLines(state, payload);
     return null;
   }
   if (event.type !== "play.run.snapshot" && event.type !== "play.run.status" && event.type !== "play.run.final_status") {
@@ -663,12 +1486,14 @@ function updatePlayLiveStatusState(state, event) {
   }
   const runId = typeof payload.runId === "string" && payload.runId ? payload.runId : isPlayRunPackage(payload) ? payload.run.id : state.runId;
   const status = normalizeLiveStatus(payload.status) ?? (isPlayRunPackage(payload) ? normalizeLiveStatus(payload.run.status) : null) ?? state.status;
-  const progressPayload = isRecord(payload.progress) ? payload.progress : {};
-  const payloadLogs = readStringArray(payload.logs);
-  const progressLogs = readStringArray(progressPayload.logs);
-  const logs = payloadLogs.length > 0 ? payloadLogs : progressLogs;
-  if (logs.length > 0 || event.type === "play.run.snapshot" || event.type === "play.run.final_status" && !isPlayRunPackage(payload)) {
-    state.logs = logs;
+  const progressPayload = isRecord2(payload.progress) ? payload.progress : {};
+  if (event.type === "play.run.final_status" && state.logs.length === 0 && state.lastLogSeq === 0) {
+    const payloadLogs = readStringArray(payload.logs);
+    const progressLogs = readStringArray(progressPayload.logs);
+    const seedLogs = payloadLogs.length > 0 ? payloadLogs : progressLogs;
+    if (seedLogs.length > 0) {
+      state.logs = seedLogs;
+    }
   }
   if ("result" in payload) {
     state.result = payload.result;
@@ -762,9 +1587,9 @@ var DeeplineClient = class {
     return fields.length > 0 ? { fields } : schema;
   }
   schemaMetadata(schema, key) {
-    if (!isRecord(schema)) return null;
+    if (!isRecord2(schema)) return null;
     const value = schema[key];
-    return isRecord(value) ? value : null;
+    return isRecord2(value) ? value : null;
   }
   playRunCommand(play, options) {
     const target = play.reference || play.name;
@@ -811,7 +1636,7 @@ var DeeplineClient = class {
       aliases,
       inputSchema: options?.compact ? this.compactSchema(play.inputSchema) : play.inputSchema ?? null,
       outputSchema: options?.compact ? this.compactSchema(play.outputSchema) : play.outputSchema ?? null,
-      staticPipeline: isRecord(play.staticPipeline) ? play.staticPipeline : isRecord(play.currentRevision?.staticPipeline) ? play.currentRevision.staticPipeline : isRecord(play.liveRevision?.staticPipeline) ? play.liveRevision.staticPipeline : null,
+      staticPipeline: isRecord2(play.staticPipeline) ? play.staticPipeline : isRecord2(play.currentRevision?.staticPipeline) ? play.currentRevision.staticPipeline : isRecord2(play.liveRevision?.staticPipeline) ? play.liveRevision.staticPipeline : null,
       ...csvInput ? { csvInput } : {},
       ...rowOutputSchema ? { rowOutputSchema } : {},
       runCommand: runCommand2,
@@ -1495,43 +2320,140 @@ var DeeplineClient = class {
     );
     return response.runs ?? [];
   }
-  /** Read the canonical run stream and return the latest run snapshot. */
-  async tailRun(runId, options) {
+  /**
+   * Observe one run's live events through the Convex Run Snapshot
+   * subscription transport (ADR-0008). Yields the same `play.*` event
+   * envelopes as {@link streamPlayRunEvents} and ends after the terminal
+   * snapshot. Throws {@link RunObserveTransportUnavailableError} when this
+   * server cannot serve the transport (older server, unconfigured grants, or
+   * unreachable Convex) — callers fall back to the SSE stream with a notice.
+   */
+  observeRunEvents(runId, options) {
+    return observeRunEvents({
+      http: this.http,
+      runId,
+      signal: options?.signal,
+      onNotice: options?.onNotice
+    });
+  }
+  /**
+   * Tail one run through the subscription transport until terminal, then
+   * return one durable REST status read (the final Run Response Package).
+   */
+  async tailRunViaObserveTransport(runId, options) {
     const state = {
       runId,
       status: "running",
       logs: [],
+      lastLogSeq: 0,
       latest: null
     };
-    let terminal = false;
-    for await (const event of this.streamPlayRunEvents(runId, {
-      mode: "cli",
-      signal: options?.signal
+    for await (const event of this.observeRunEvents(runId, {
+      signal: options?.signal,
+      onNotice: options?.onNotice
     })) {
       const status = updatePlayLiveStatusState(state, event);
-      if (!status) {
+      if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {
         continue;
       }
-      terminal = TERMINAL_PLAY_STATUSES.has(status.status);
-      if (terminal) {
-        break;
-      }
-    }
-    if (terminal && state.latest) {
-      return await this.getRunStatus(state.latest.runId || runId).catch(
+      return await this.getRunStatus(status.runId || runId).catch(
         () => state.latest ?? playRunStatusFromState(state)
       );
     }
-    if (state.latest) {
-      return state.latest;
+    if (options?.signal?.aborted) {
+      throw new DeeplineError("Run observation aborted.", void 0, "ABORTED");
+    }
+    const refreshed = await this.getRunStatus(runId);
+    if (TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
+      return refreshed;
     }
     throw new DeeplineError(
-      `Run stream for ${runId} ended before the initial snapshot.`,
+      `Run observation for ${runId} ended before a terminal status.`,
       void 0,
-      "PLAY_RUN_STREAM_EMPTY",
-      { runId }
+      "PLAY_LIVE_STREAM_ENDED"
     );
   }
+  /**
+   * Read the canonical run stream until a terminal run status is observed.
+   *
+   * Tries the Convex Run Snapshot subscription transport first (ADR-0008);
+   * when the server cannot serve it (grant endpoint missing/unconfigured or
+   * Convex unreachable) it falls back — with one `onNotice` message — to the
+   * support-window SSE stream below.
+   *
+   * Server stream windows are finite: they end cleanly at the function
+   * ceiling even while the run keeps executing. A window that ends (cleanly
+   * or via transient network error) without a terminal event triggers one
+   * durable-status re-check followed by a backed-off reconnect, so long runs
+   * tail to completion. Abort via `options.signal` to stop waiting.
+   */
+  async tailRun(runId, options) {
+    try {
+      return await this.tailRunViaObserveTransport(runId, options);
+    } catch (error) {
+      if (!(error instanceof RunObserveTransportUnavailableError)) {
+        throw error;
+      }
+      options?.onNotice?.(
+        `[observe] live subscription unavailable (${error.reason}); falling back to SSE tail (support window, ADR-0008)`
+      );
+    }
+    const state = {
+      runId,
+      status: "running",
+      logs: [],
+      lastLogSeq: 0,
+      latest: null
+    };
+    let reconnectAttempt = 0;
+    for (; ; ) {
+      const connectedAt = Date.now();
+      let sawEvent = false;
+      let endedReason = "stream window ended before a terminal event";
+      try {
+        for await (const event of this.streamPlayRunEvents(runId, {
+          mode: "cli",
+          signal: options?.signal
+        })) {
+          sawEvent = true;
+          const status = updatePlayLiveStatusState(state, event);
+          if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {
+            continue;
+          }
+          return await this.getRunStatus(status.runId || runId).catch(
+            () => state.latest ?? playRunStatusFromState(state)
+          );
+        }
+      } catch (error) {
+        if (options?.signal?.aborted || !isTransientPlayStreamError(error)) {
+          throw error;
+        }
+        endedReason = error instanceof Error ? error.message : String(error);
+      }
+      let refreshed = null;
+      try {
+        refreshed = await this.getRunStatus(runId);
+      } catch (error) {
+        if (!isTransientPlayStreamError(error)) {
+          throw error;
+        }
+      }
+      if (refreshed && TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
+        return refreshed;
+      }
+      if (sawEvent || Date.now() - connectedAt >= STREAM_HEALTHY_CONNECTION_MS) {
+        reconnectAttempt = 0;
+      }
+      const delayMs = streamReconnectDelayMs(reconnectAttempt);
+      reconnectAttempt += 1;
+      options?.onReconnect?.({
+        attempt: reconnectAttempt,
+        delayMs,
+        reason: endedReason
+      });
+      await sleep2(delayMs);
+    }
+  }
   /**
    * Fetch persisted logs for a run using the public runs resource model.
    *
@@ -1542,19 +2464,40 @@ var DeeplineClient = class {
    * ```
    */
   async getRunLogs(runId, options) {
-    const status = await this.getRunStatus(runId, { full: true });
-    const logs = status.progress?.logs ?? [];
-    const limit = typeof options?.limit === "number" && Number.isFinite(options.limit) ? Math.max(0, Math.trunc(options.limit)) : 200;
-    const entries = logs.slice(Math.max(0, logs.length - limit));
+    const limit = options?.all ? Number.MAX_SAFE_INTEGER : typeof options?.limit === "number" && Number.isFinite(options.limit) && options.limit > 0 ? Math.trunc(options.limit) : 200;
+    const fetchPage = (afterSeq2, pageLimit) => this.http.get(
+      `/api/v2/runs/${encodeURIComponent(runId)}/logs?afterSeq=${afterSeq2}&limit=${pageLimit}`
+    );
+    const probe = await fetchPage(0, 1);
+    const lastStoredSeq = probe.lastStoredSeq;
+    let afterSeq = options?.all ? 0 : Math.max(0, lastStoredSeq - limit);
+    const entries = [];
+    while (entries.length < limit) {
+      const page = await fetchPage(
+        afterSeq,
+        Math.min(RUN_LOGS_PAGE_LIMIT, limit - entries.length)
+      );
+      if (page.entries.length === 0) {
+        break;
+      }
+      entries.push(...page.entries);
+      afterSeq = page.entries[page.entries.length - 1].seq;
+      if (!page.hasMore) {
+        break;
+      }
+    }
+    const firstSequence = entries.length > 0 ? entries[0].seq : null;
+    const lastSequence = entries.length > 0 ? entries[entries.length - 1].seq : null;
     return {
-      runId: status.runId,
-      totalCount: logs.length,
+      runId: probe.runId,
+      totalCount: probe.totalLogCount,
       returnedCount: entries.length,
-      firstSequence: logs.length === 0 ? null : logs.length - entries.length + 1,
-      lastSequence: logs.length === 0 ? null : logs.length,
-      truncated: logs.length > entries.length,
-      hasMore: logs.length > entries.length,
-      entries
+      firstSequence,
+      lastSequence,
+      truncated: entries.length < probe.totalLogCount,
+      hasMore: lastSequence !== null && lastSequence < lastStoredSeq,
+      entries: entries.map((entry) => entry.line),
+      ...probe.logsTruncated ? { logsTruncated: true } : {}
     };
   }
   /**
@@ -1845,6 +2788,7 @@ var DeeplineClient = class {
       runId: workflowId,
       status: "running",
       logs: [],
+      lastLogSeq: 0,
       latest: null
     };
     if (options?.signal?.aborted) {
@@ -3539,11 +4483,11 @@ function sanitizeCsvProjectionInfo(input2) {
   const rows = input2.rows.map(stripCsvProjectionFields);
   return { rows, columns };
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function isSerializedDataset(value) {
-  return isRecord2(value) && value.kind === "dataset" && typeof value.count === "number" && Array.isArray(value.preview);
+  return isRecord3(value) && value.kind === "dataset" && typeof value.count === "number" && Array.isArray(value.preview);
 }
 function pathParts(path) {
   return path.split(".").map((part) => part.trim()).filter(Boolean);
@@ -3551,7 +4495,7 @@ function pathParts(path) {
 function valueAtPath(root, path) {
   let cursor = root;
   for (const part of pathParts(path)) {
-    if (!isRecord2(cursor)) {
+    if (!isRecord3(cursor)) {
       return void 0;
     }
     cursor = cursor[part];
@@ -3559,17 +4503,17 @@ function valueAtPath(root, path) {
   return cursor;
 }
 function totalRowsForDataset(result, datasetPath) {
-  const metadata = isRecord2(result._metadata) ? result._metadata : null;
+  const metadata = isRecord3(result._metadata) ? result._metadata : null;
   const parentPath = datasetPath.split(".").slice(0, -1).join(".");
   const parent = parentPath ? valueAtPath({ result }, parentPath) : result;
-  return metadata?.totalRows ?? metadata?.rowCount ?? metadata?.count ?? (isRecord2(parent) ? parent.totalRows ?? parent.rowCount ?? parent.count : void 0) ?? result.totalRows ?? result.rowCount ?? result.count;
+  return metadata?.totalRows ?? metadata?.rowCount ?? metadata?.count ?? (isRecord3(parent) ? parent.totalRows ?? parent.rowCount ?? parent.count : void 0) ?? result.totalRows ?? result.rowCount ?? result.count;
 }
 function rowArray(value) {
   if (!Array.isArray(value)) {
     return null;
   }
   const rows = value.filter(
-    (row) => isRecord2(row)
+    (row) => isRecord3(row)
   );
   return rows.length === value.length ? rows : null;
 }
@@ -3646,7 +4590,7 @@ function collectDatasetCandidates(input2) {
     });
     return;
   }
-  if (!isRecord2(input2.value)) {
+  if (!isRecord3(input2.value)) {
     return;
   }
   for (const [key, child] of Object.entries(input2.value)) {
@@ -3663,12 +4607,12 @@ function collectDatasetCandidates(input2) {
   }
 }
 function collectCanonicalRowsInfos(statusOrResult) {
-  const root = isRecord2(statusOrResult) ? statusOrResult : null;
-  const result = isRecord2(root?.result) ? root.result : root;
+  const root = isRecord3(statusOrResult) ? statusOrResult : null;
+  const result = isRecord3(root?.result) ? root.result : root;
   if (!result) {
     return [];
   }
-  const metadata = isRecord2(result._metadata) ? result._metadata : null;
+  const metadata = isRecord3(result._metadata) ? result._metadata : null;
   const totalFromMetadata = metadata?.totalRows ?? metadata?.rowCount ?? metadata?.count;
   const candidates = [
     {
@@ -3692,8 +4636,8 @@ function collectCanonicalRowsInfos(statusOrResult) {
       total: totalFromMetadata ?? result.totalRows ?? result.rowCount ?? result.count
     }
   ];
-  if (isRecord2(result.output)) {
-    const outputMetadata = isRecord2(result.output._metadata) ? result.output._metadata : null;
+  if (isRecord3(result.output)) {
+    const outputMetadata = isRecord3(result.output._metadata) ? result.output._metadata : null;
     const outputTotalFromMetadata = outputMetadata?.totalRows ?? outputMetadata?.rowCount ?? outputMetadata?.count;
     candidates.push(
       {
@@ -3739,8 +4683,8 @@ function collectCanonicalRowsInfos(statusOrResult) {
   return infos;
 }
 function collectSerializedDatasetRowsInfos(statusOrResult) {
-  const root = isRecord2(statusOrResult) ? statusOrResult : null;
-  const result = isRecord2(root?.result) ? root.result : root;
+  const root = isRecord3(statusOrResult) ? statusOrResult : null;
+  const result = isRecord3(root?.result) ? root.result : root;
   if (!result) {
     return [];
   }
@@ -3774,17 +4718,17 @@ function percentText(numerator, denominator) {
   return datasetSummaryPercentText(numerator, denominator);
 }
 function isDatasetExecutionStatsInput(value) {
-  return isRecord2(value) && isRecord2(value.columnStats) && Object.values(value.columnStats).every(isRecord2);
+  return isRecord3(value) && isRecord3(value.columnStats) && Object.values(value.columnStats).every(isRecord3);
 }
 function extractDatasetExecutionStats(statusOrResult) {
-  if (!isRecord2(statusOrResult)) {
+  if (!isRecord3(statusOrResult)) {
     return null;
   }
   const direct = statusOrResult.dataset_execution_stats;
   if (isDatasetExecutionStatsInput(direct)) {
     return direct;
   }
-  const nested = isRecord2(statusOrResult.result) ? statusOrResult.result.dataset_execution_stats : null;
+  const nested = isRecord3(statusOrResult.result) ? statusOrResult.result.dataset_execution_stats : null;
   return isDatasetExecutionStatsInput(nested) ? nested : null;
 }
 function countPercentText(count, denominator) {
@@ -3825,13 +4769,13 @@ function summarizeSampleValue(value, depth = 0) {
   if (typeof parsed === "number" || typeof parsed === "boolean") return parsed;
   if (depth >= 3) {
     if (Array.isArray(parsed)) return [];
-    if (isRecord2(parsed)) return {};
+    if (isRecord3(parsed)) return {};
     return compactScalar(parsed);
   }
   if (Array.isArray(parsed)) {
     return parsed.slice(0, 3).map((item) => summarizeSampleValue(item, depth + 1));
   }
-  if (isRecord2(parsed)) {
+  if (isRecord3(parsed)) {
     const out = {};
     for (const [key, nested] of Object.entries(parsed)) {
       if (["__dl", "meta", "metadata"].includes(key)) {
@@ -3862,7 +4806,7 @@ function compactCell(value) {
     }
     return `[${parsed.length} items]`;
   }
-  if (isRecord2(parsed)) {
+  if (isRecord3(parsed)) {
     for (const key of ["matched_result", "output"]) {
       if (parsed[key] !== null && parsed[key] !== void 0 && parsed[key] !== "") {
         return compactCell(parsed[key]);
@@ -6201,17 +7145,17 @@ function parsePositiveInteger2(value, flagName) {
   }
   return parsed;
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function stringValue(value) {
   return typeof value === "string" ? value.trim() : "";
 }
 function extractionEntries(value) {
-  if (Array.isArray(value)) return value.filter(isRecord3);
-  if (!isRecord3(value)) return [];
+  if (Array.isArray(value)) return value.filter(isRecord4);
+  if (!isRecord4(value)) return [];
   return Object.entries(value).map(
-    ([name, entry]) => isRecord3(entry) ? { name, ...entry } : { name }
+    ([name, entry]) => isRecord4(entry) ? { name, ...entry } : { name }
   );
 }
 var PlayBootstrapError = class extends Error {
@@ -6631,7 +7575,7 @@ function readCsvSampleRows(sample) {
     relax_column_count: true,
     trim: true
   });
-  return Array.isArray(parsedRows) ? parsedRows.filter(isRecord3) : [];
+  return Array.isArray(parsedRows) ? parsedRows.filter(isRecord4) : [];
 }
 function readSourceCsvColumnSpecs(csvPath) {
   const sample = readCsvSample(csvPath);
@@ -6664,16 +7608,16 @@ function packagedCsvPathForPlay(csvPath) {
   return portablePath.startsWith(".") ? portablePath : `./${portablePath}`;
 }
 function getterNamesFromTool(tool, kind) {
-  const usageGuidance = isRecord3(tool?.usageGuidance) ? tool.usageGuidance : {};
-  const resultGuidance = isRecord3(usageGuidance.toolExecutionResult) ? usageGuidance.toolExecutionResult : isRecord3(usageGuidance.tool_execution_result) ? usageGuidance.tool_execution_result : {};
+  const usageGuidance = isRecord4(tool?.usageGuidance) ? tool.usageGuidance : {};
+  const resultGuidance = isRecord4(usageGuidance.toolExecutionResult) ? usageGuidance.toolExecutionResult : isRecord4(usageGuidance.tool_execution_result) ? usageGuidance.tool_execution_result : {};
   const key = kind === "list" ? "extractedLists" : "extractedValues";
   const snakeKey = kind === "list" ? "extracted_lists" : "extracted_values";
   return extractionEntries(resultGuidance[key] ?? resultGuidance[snakeKey]).map((entry) => stringValue(entry.name)).filter(Boolean);
 }
 function targetGettersFromTool(tool) {
-  const record = isRecord3(tool) ? tool : {};
+  const record = isRecord4(tool) ? tool : {};
   const raw = record.targetGetters ?? record.target_getters;
-  if (!isRecord3(raw)) return {};
+  if (!isRecord4(raw)) return {};
   const entries = [];
   for (const [target, value] of Object.entries(raw)) {
     const paths = Array.isArray(value) ? value.map((path) => typeof path === "string" ? path.trim() : "").filter(Boolean) : [];
@@ -6694,10 +7638,10 @@ function listRowCandidateKeysFromTool(tool) {
   return [...keys].sort();
 }
 function inputPropertyNames(schema) {
-  if (!isRecord3(schema)) return [];
-  if (isRecord3(schema.properties)) return Object.keys(schema.properties);
+  if (!isRecord4(schema)) return [];
+  if (isRecord4(schema.properties)) return Object.keys(schema.properties);
   if (Array.isArray(schema.fields)) {
-    return schema.fields.filter(isRecord3).map((field) => stringValue(field.name)).filter(Boolean);
+    return schema.fields.filter(isRecord4).map((field) => stringValue(field.name)).filter(Boolean);
   }
   return [];
 }
@@ -6711,7 +7655,7 @@ function schemaFieldDetails(schema) {
   return { required, optional };
 }
 function jsonSchemaTypeExpression(schema) {
-  if (!isRecord3(schema)) return "unknown";
+  if (!isRecord4(schema)) return "unknown";
   const type = schema.type;
   if (Array.isArray(type)) {
     return type.map((entry) => jsonSchemaTypeExpression({ ...schema, type: entry })).join(" | ");
@@ -6741,7 +7685,7 @@ function jsonSchemaTypeExpression(schema) {
   }
 }
 function objectPropertySchema(schema, property) {
-  return isRecord3(schema) && isRecord3(schema.properties) ? schema.properties[property] : null;
+  return isRecord4(schema) && isRecord4(schema.properties) ? schema.properties[property] : null;
 }
 function playOutputHasField(schema, field) {
   return objectPropertySchema(schema, field) != null;
@@ -6917,14 +7861,14 @@ ${indent2.slice(2)}}`;
 }
 function requiredPlayInputFields(play) {
   const schema = play?.inputSchema;
-  if (!isRecord3(schema)) return [];
+  if (!isRecord4(schema)) return [];
   if (Array.isArray(schema.required)) {
     return schema.required.filter(
       (value) => typeof value === "string"
     );
   }
   if (Array.isArray(schema.fields)) {
-    return schema.fields.filter(isRecord3).filter(
+    return schema.fields.filter(isRecord4).filter(
       (field) => field.required === true && typeof field.name === "string"
     ).map((field) => String(field.name));
   }
@@ -7105,7 +8049,7 @@ function validateBootstrapRoutes(input2) {
   }
 }
 function staticPipelineSubsteps(pipeline) {
-  if (!isRecord3(pipeline)) return [];
+  if (!isRecord4(pipeline)) return [];
   return [
     ...extractionEntries(pipeline.stages),
     ...extractionEntries(pipeline.substeps)
@@ -7113,7 +8057,7 @@ function staticPipelineSubsteps(pipeline) {
 }
 function playUsesMapBackedRuntime(play) {
   const pipeline = play?.staticPipeline;
-  if (!isRecord3(pipeline)) return false;
+  if (!isRecord4(pipeline)) return false;
   if (stringValue(pipeline.tableNamespace)) return true;
   return staticPipelineSubsteps(pipeline).some((substep) => {
     if (stringValue(substep.type) === "map") return true;
@@ -7122,7 +8066,7 @@ function playUsesMapBackedRuntime(play) {
       aliases: [],
       runCommand: "",
       examples: [],
-      staticPipeline: isRecord3(substep.pipeline) ? substep.pipeline : null
+      staticPipeline: isRecord4(substep.pipeline) ? substep.pipeline : null
     });
   });
 }
@@ -8447,15 +9391,6 @@ function formatRunLine(run) {
   const credits = typeof run.billingTotalCredits === "number" && Number.isFinite(run.billingTotalCredits) ? `${formatCreditAmount(run.billingTotalCredits)} credits` : "\u2014";
   return `${run.workflowId} ${run.status} ${formatTimestamp(run.startTime)} ${credits}`;
 }
-function isTransientPlayStreamError(error) {
-  if (error instanceof DeeplineError && typeof error.statusCode === "number") {
-    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 playStatusErrorText(status) {
   const chunks = [];
   const progressError = status.progress?.error;
@@ -8793,97 +9728,227 @@ function assertPlayWaitNotTimedOut(input2) {
   }
 }
 async function waitForPlayCompletionByStream(input2) {
-  const controller = new AbortController();
-  let timedOut = false;
   let lastPhase = null;
-  const timeout = input2.waitTimeoutMs === null ? null : setTimeout(
-    () => {
-      timedOut = true;
-      controller.abort();
-    },
-    Math.max(1, input2.waitTimeoutMs - (Date.now() - input2.startedAt))
-  );
-  try {
-    for await (const event of input2.client.streamPlayRunEvents(
-      input2.workflowId,
-      { signal: controller.signal }
-    )) {
-      assertPlayWaitNotTimedOut({ ...input2, lastPhase });
-      const phase = describeLiveEventPhase(event);
-      if (phase) {
-        lastPhase = phase;
-        input2.progress.phase(phase);
-      }
-      emitLiveDebugTableHints({
-        event,
-        playName: input2.playName,
-        runId: input2.workflowId,
-        jsonOutput: input2.jsonOutput,
-        state: input2.state,
-        progress: input2.progress
+  let reconnectAttempt = 0;
+  const withDashboardUrl = (status) => input2.dashboardUrl ? { ...status, dashboardUrl: input2.dashboardUrl } : status;
+  const remainingWaitMs = () => input2.waitTimeoutMs === null ? null : input2.waitTimeoutMs - (Date.now() - input2.startedAt);
+  const fetchTerminalStatus = async () => {
+    let refreshed;
+    try {
+      refreshed = await input2.client.getPlayStatus(input2.workflowId, {
+        billing: false
       });
-      printPlayLogLines({
-        lines: getLogLinesFromLiveEvent(event),
-        status: null,
-        jsonOutput: input2.jsonOutput,
-        emitLogs: input2.emitLogs,
+    } catch (error) {
+      if (isTransientPlayStreamError(error)) {
+        return null;
+      }
+      throw error;
+    }
+    return TERMINAL_PLAY_STATUSES2.has(refreshed.status) ? withDashboardUrl(refreshed) : null;
+  };
+  const handleLiveEvent = async (event) => {
+    assertPlayWaitNotTimedOut({ ...input2, lastPhase });
+    const phase = describeLiveEventPhase(event);
+    if (phase) {
+      lastPhase = phase;
+      input2.progress.phase(phase);
+    }
+    emitLiveDebugTableHints({
+      event,
+      playName: input2.playName,
+      runId: input2.workflowId,
+      jsonOutput: input2.jsonOutput,
+      state: input2.state,
+      progress: input2.progress
+    });
+    printPlayLogLines({
+      lines: getLogLinesFromLiveEvent(event),
+      status: null,
+      jsonOutput: input2.jsonOutput,
+      emitLogs: input2.emitLogs,
+      state: input2.state,
+      progress: input2.progress
+    });
+    if (!input2.jsonOutput) {
+      const progressLines = getProgressLinesFromLiveEvent(event);
+      printPlayProgressLines({
+        lines: progressLines,
         state: input2.state,
         progress: input2.progress
       });
-      if (!input2.jsonOutput) {
-        const progressLines = getProgressLinesFromLiveEvent(event);
-        printPlayProgressLines({
-          lines: progressLines,
+      if (progressLines.length === 0) {
+        printPlayStatusHeartbeat({
+          event,
+          playName: input2.playName,
           state: input2.state,
           progress: input2.progress
         });
-        if (progressLines.length === 0) {
-          printPlayStatusHeartbeat({
-            event,
-            playName: input2.playName,
-            state: input2.state,
-            progress: input2.progress
-          });
-        }
       }
-      const finalStatus = getFinalStatusFromLiveEvent(event);
-      if (finalStatus) {
-        return input2.dashboardUrl ? { ...finalStatus, dashboardUrl: input2.dashboardUrl } : finalStatus;
+    }
+    const finalStatus = getFinalStatusFromLiveEvent(event);
+    if (finalStatus) {
+      return withDashboardUrl(finalStatus);
+    }
+    const status = getStatusFromLiveEvent(event);
+    if (status && TERMINAL_PLAY_STATUSES2.has(status)) {
+      const refreshedStatus = await input2.client.getPlayStatus(
+        input2.workflowId,
+        {
+          billing: false
+        }
+      );
+      if (TERMINAL_PLAY_STATUSES2.has(refreshedStatus.status)) {
+        return withDashboardUrl(refreshedStatus);
       }
-      const status = getStatusFromLiveEvent(event);
-      if (status && TERMINAL_PLAY_STATUSES2.has(status)) {
-        const refreshedStatus = await input2.client.getPlayStatus(
-          input2.workflowId,
-          {
-            billing: false
-          }
-        );
-        if (TERMINAL_PLAY_STATUSES2.has(refreshedStatus.status)) {
-          return input2.dashboardUrl ? { ...refreshedStatus, dashboardUrl: input2.dashboardUrl } : refreshedStatus;
+    }
+    return null;
+  };
+  const watchViaObserveTransport = async () => {
+    const controller = new AbortController();
+    let timedOut = false;
+    const remaining = remainingWaitMs();
+    const timeout = remaining === null ? null : setTimeout(
+      () => {
+        timedOut = true;
+        controller.abort();
+      },
+      Math.max(1, remaining)
+    );
+    try {
+      for await (const event of input2.client.observeRunEvents(
+        input2.workflowId,
+        {
+          signal: controller.signal,
+          onNotice: input2.jsonOutput ? void 0 : (message) => input2.progress.writeLine(message)
+        }
+      )) {
+        const terminal2 = await handleLiveEvent(event);
+        if (terminal2) {
+          return terminal2;
         }
       }
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+    const terminal = await fetchTerminalStatus();
+    if (terminal) {
+      return terminal;
     }
-  } catch (error) {
     if (timedOut) {
       assertPlayWaitNotTimedOut({ ...input2, lastPhase });
     }
-    throw error;
-  } finally {
-    if (timeout) {
-      clearTimeout(timeout);
+    throw new DeeplineError(
+      `Run observation for ${input2.workflowId} ended before a terminal status.`,
+      void 0,
+      "PLAY_LIVE_STREAM_ENDED",
+      { runId: input2.workflowId, workflowId: input2.workflowId }
+    );
+  };
+  try {
+    return await watchViaObserveTransport();
+  } catch (error) {
+    if (!(error instanceof RunObserveTransportUnavailableError)) {
+      throw error;
     }
-  }
-  const phaseSuffix = lastPhase && lastPhase.trim() ? ` (last observed phase: ${lastPhase.trim()})` : "";
-  throw new DeeplineError(
-    `Play watch stream ended before the run reached a terminal status. runId=${input2.workflowId}${phaseSuffix}. Inspect the current run with 'deepline runs get ${input2.workflowId} --full --json' or continue watching with 'deepline runs tail ${input2.workflowId}'.`,
-    void 0,
-    "PLAY_LIVE_STREAM_ENDED",
-    {
-      runId: input2.workflowId,
+    if (!input2.jsonOutput) {
+      input2.progress.writeLine(
+        `[play watch] live subscription unavailable (${error.reason}); falling back to SSE tail (support window, ADR-0008)`
+      );
+    }
+    recordCliTrace({
+      phase: "cli.play_observe_transport_fallback",
+      ms: Date.now() - input2.startedAt,
+      ok: true,
+      playName: input2.playName,
       workflowId: input2.workflowId,
-      ...lastPhase ? { phase: lastPhase } : {}
+      reason: error.reason
+    });
+  }
+  const streamOneWindow = async () => {
+    const controller = new AbortController();
+    let timedOut = false;
+    let sawEvent = false;
+    const remaining = remainingWaitMs();
+    const timeout = remaining === null ? null : setTimeout(
+      () => {
+        timedOut = true;
+        controller.abort();
+      },
+      Math.max(1, remaining)
+    );
+    try {
+      for await (const event of input2.client.streamPlayRunEvents(
+        input2.workflowId,
+        { signal: controller.signal }
+      )) {
+        sawEvent = true;
+        const terminal = await handleLiveEvent(event);
+        if (terminal) {
+          return { kind: "terminal", status: terminal };
+        }
+      }
+    } catch (error) {
+      if (timedOut) {
+        return { kind: "timed_out", sawEvent };
+      }
+      if (!isTransientPlayStreamError(error)) {
+        throw error;
+      }
+      return {
+        kind: "ended",
+        sawEvent,
+        reason: error instanceof Error ? error.message : String(error)
+      };
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
     }
-  );
+    return {
+      kind: "ended",
+      sawEvent,
+      reason: "stream window ended before a terminal event"
+    };
+  };
+  for (; ; ) {
+    const connectedAt = Date.now();
+    const window = await streamOneWindow();
+    if (window.kind === "terminal") {
+      return window.status;
+    }
+    const terminal = await fetchTerminalStatus();
+    if (terminal) {
+      return terminal;
+    }
+    assertPlayWaitNotTimedOut({ ...input2, lastPhase });
+    if (window.sawEvent || Date.now() - connectedAt >= STREAM_HEALTHY_CONNECTION_MS) {
+      reconnectAttempt = 0;
+    }
+    const delayMs = streamReconnectDelayMs(reconnectAttempt);
+    reconnectAttempt += 1;
+    const reason = window.kind === "ended" ? window.reason : "wait timeout raced the stream";
+    if (!input2.jsonOutput) {
+      input2.progress.writeLine(
+        `[play watch] stream ended without a terminal status; reconnecting to run ${input2.workflowId} (${reason})`
+      );
+    }
+    recordCliTrace({
+      phase: "cli.play_tail_stream_reconnect",
+      ms: Date.now() - input2.startedAt,
+      ok: true,
+      playName: input2.playName,
+      workflowId: input2.workflowId,
+      attempt: reconnectAttempt,
+      delayMs,
+      reason
+    });
+    const remainingBeforeSleep = remainingWaitMs();
+    await sleep4(
+      remainingBeforeSleep === null ? delayMs : Math.min(delayMs, Math.max(1, remainingBeforeSleep))
+    );
+  }
 }
 async function startAndWaitForPlayCompletionByStream(input2) {
   for (let attempt = 0; attempt <= PLAY_START_TRANSIENT_RETRY_DELAYS_MS.length; attempt += 1) {
@@ -9828,6 +10893,10 @@ function buildRunPackageTextLines(packaged) {
   const lines = [
     `${status === "completed" ? "\u2713" : status === "failed" ? "\u2717" : "\u2022"} ${status}  ${runId}`
   ];
+  const runError = typeof run.error === "string" && run.error.trim() ? run.error.trim() : null;
+  if (runError && (status === "failed" || status === "cancelled")) {
+    lines.push(`  error: ${runError.slice(0, 200)}`);
+  }
   if (playName) {
     lines.push(`  play: ${playName}`);
   }
@@ -9929,18 +10998,33 @@ function writePlayResult(status, jsonOutput, options) {
 ` }
   );
 }
+function playRunPackageStepCount(pkg) {
+  if (!pkg) return 0;
+  const steps = pkg.steps;
+  return Array.isArray(steps) ? steps.length : 0;
+}
 async function resolvePlayRunOutputStatus(input2) {
-  if (!input2.fullJson || !getPlayRunPackage(input2.status)) {
-    return input2.status;
-  }
   const runId = input2.status.runId;
   if (!runId) {
     return input2.status;
   }
-  const refreshedStatus = await input2.client.getPlayStatus(runId, {
+  const streamedPackage = getPlayRunPackage(input2.status);
+  const refreshForFullJson = input2.fullJson && streamedPackage !== null;
+  const streamedTextPackageIncomplete = !input2.jsonOutput && input2.status.status === "completed" && playRunPackageStepCount(streamedPackage) === 0;
+  if (!refreshForFullJson && !streamedTextPackageIncomplete) {
+    return input2.status;
+  }
+  let refreshedStatus = await input2.client.getPlayStatus(runId, {
     billing: false,
     full: input2.fullJson
   });
+  for (let attempt = 0; attempt < 3 && streamedTextPackageIncomplete && refreshedStatus.status === "completed" && playRunPackageStepCount(getPlayRunPackage(refreshedStatus)) === 0; attempt += 1) {
+    await sleep4(250);
+    refreshedStatus = await input2.client.getPlayStatus(runId, {
+      billing: false,
+      full: input2.fullJson
+    });
+  }
   const dashboardUrl = input2.status.dashboardUrl;
   return typeof dashboardUrl === "string" ? { ...refreshedStatus, dashboardUrl } : refreshedStatus;
 }
@@ -10194,7 +11278,7 @@ function extractPlayValidationErrors(value) {
   if (value instanceof DeeplineError) {
     return extractPlayValidationErrors(value.details);
   }
-  if (!isRecord4(value)) {
+  if (!isRecord5(value)) {
     return [];
   }
   const directErrors = stringArrayField(value, "errors");
@@ -10552,7 +11636,7 @@ function shouldUseLocalOnlyPlayCheck() {
   const value = process.env.DEEPLINE_PLAY_CHECK_LOCAL_ONLY?.trim().toLowerCase();
   return value === "1" || value === "true" || value === "yes" || value === "on";
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function stringValue2(value) {
@@ -10562,14 +11646,14 @@ function asArray(value) {
   return Array.isArray(value) ? value : [];
 }
 function extractionEntries2(value) {
-  if (Array.isArray(value)) return value.filter(isRecord4);
-  if (!isRecord4(value)) return [];
+  if (Array.isArray(value)) return value.filter(isRecord5);
+  if (!isRecord5(value)) return [];
   return Object.entries(value).map(
-    ([name, entry]) => isRecord4(entry) ? { name, ...entry } : { name }
+    ([name, entry]) => isRecord5(entry) ? { name, ...entry } : { name }
   );
 }
 function firstRawPath(entry) {
-  const details = isRecord4(entry.details) ? entry.details : {};
+  const details = isRecord5(entry.details) ? entry.details : {};
   const paths = [
     ...asArray(details.rawToolOutputPaths),
     ...asArray(details.raw_tool_output_paths),
@@ -10587,12 +11671,12 @@ function checkHintRawPath(value) {
 function collectStaticPipelineToolIds(staticPipeline) {
   const seen = /* @__PURE__ */ new Set();
   const visitPipeline = (pipeline) => {
-    if (!isRecord4(pipeline)) return;
+    if (!isRecord5(pipeline)) return;
     for (const step of [
       ...asArray(pipeline.stages),
       ...asArray(pipeline.substeps)
     ]) {
-      if (!isRecord4(step)) continue;
+      if (!isRecord5(step)) continue;
       if (step.type === "tool") {
         const toolId = stringValue2(step.toolId) || stringValue2(step.tool);
         if (toolId) seen.add(toolId);
@@ -10606,9 +11690,9 @@ function collectStaticPipelineToolIds(staticPipeline) {
   return [...seen].sort();
 }
 function toolGetterHintFromMetadata(toolId, tool) {
-  const usageGuidance = isRecord4(tool.usageGuidance) ? tool.usageGuidance : {};
-  const resultGuidance = isRecord4(usageGuidance.toolExecutionResult) ? usageGuidance.toolExecutionResult : isRecord4(usageGuidance.tool_execution_result) ? usageGuidance.tool_execution_result : {};
-  const toolResponse = isRecord4(resultGuidance.toolResponse) ? resultGuidance.toolResponse : isRecord4(resultGuidance.tool_response) ? resultGuidance.tool_response : {};
+  const usageGuidance = isRecord5(tool.usageGuidance) ? tool.usageGuidance : {};
+  const resultGuidance = isRecord5(usageGuidance.toolExecutionResult) ? usageGuidance.toolExecutionResult : isRecord5(usageGuidance.tool_execution_result) ? usageGuidance.tool_execution_result : {};
+  const toolResponse = isRecord5(resultGuidance.toolResponse) ? resultGuidance.toolResponse : isRecord5(resultGuidance.tool_response) ? resultGuidance.tool_response : {};
   const lists = extractionEntries2(
     resultGuidance.extractedLists ?? resultGuidance.extracted_lists
   ).map((entry) => ({
@@ -10904,7 +11988,8 @@ async function handleFileBackedRun(options) {
       await resolvePlayRunOutputStatus({
         client,
         status: finalStatus,
-        fullJson: options.fullJson
+        fullJson: options.fullJson,
+        jsonOutput: options.jsonOutput
       }),
       playName
     );
@@ -11054,7 +12139,8 @@ async function handleNamedRun(options) {
       await resolvePlayRunOutputStatus({
         client,
         status: finalStatus,
-        fullJson: options.fullJson
+        fullJson: options.fullJson,
+        jsonOutput: options.jsonOutput
       }),
       playName
     );
@@ -11235,8 +12321,17 @@ async function handleRunTail(args) {
     }
   }
   const client = new DeeplineClient();
-  const status = await client.runs.tail(runId);
-  writePlayResult(status, argsWantJson(args));
+  const jsonOutput = argsWantJson(args);
+  const status = await client.runs.tail(runId, {
+    // Human mode only: in --json mode emit nothing non-protocol.
+    onReconnect: jsonOutput ? void 0 : ({ reason }) => {
+      process.stderr.write(
+        `[runs tail] stream ended without a terminal status; reconnecting to run ${runId} (${reason})
+`
+      );
+    }
+  });
+  writePlayResult(status, jsonOutput);
   return status.status === "failed" ? 1 : 0;
 }
 async function handleRunLogs(args) {
@@ -11261,21 +12356,28 @@ async function handleRunLogs(args) {
     }
   }
   const client = new DeeplineClient();
-  const status = await client.runs.get(runId, { full: true });
-  const logs = status.progress?.logs ?? [];
   if (outPath) {
+    const result2 = await client.runs.logs(runId, { all: true });
+    const logs = result2.entries;
     writeFileSync7(outPath, `${logs.join("\n")}${logs.length > 0 ? "\n" : ""}`);
     printCommandEnvelope(
       {
-        runId: status.runId,
+        runId: result2.runId,
         log_path: outPath,
         lineCount: logs.length,
+        totalCount: result2.totalCount,
+        ...result2.logsTruncated ? { logsTruncated: true } : {},
         local: { log_path: outPath },
         render: {
           sections: [
             {
               title: "run logs",
-              lines: [`Wrote ${logs.length} log lines to ${outPath}`]
+              lines: [
+                `Wrote ${logs.length} log lines to ${outPath}`,
+                ...result2.logsTruncated ? [
+                  `Run crossed the log retention cap: ${result2.totalCount} lines were emitted, stored bodies end at the truncation marker.`
+                ] : []
+              ]
             }
           ]
         }
@@ -11284,25 +12386,26 @@ async function handleRunLogs(args) {
     );
     return 0;
   }
-  const entries = logs.slice(Math.max(0, logs.length - limit));
+  const result = await client.runs.logs(runId, { limit });
   printCommandEnvelope(
     {
-      runId: status.runId,
-      totalCount: logs.length,
-      returnedCount: entries.length,
-      firstSequence: logs.length === 0 ? null : logs.length - entries.length + 1,
-      lastSequence: logs.length === 0 ? null : logs.length,
-      truncated: logs.length > entries.length,
-      hasMore: logs.length > entries.length,
-      entries,
+      runId: result.runId,
+      totalCount: result.totalCount,
+      returnedCount: result.returnedCount,
+      firstSequence: result.firstSequence,
+      lastSequence: result.lastSequence,
+      truncated: result.truncated,
+      hasMore: result.hasMore,
+      ...result.logsTruncated ? { logsTruncated: true } : {},
+      entries: result.entries,
       next: {
-        export: `deepline runs logs ${status.runId} --out run.log --json`
+        export: `deepline runs logs ${result.runId} --out run.log --json`
       },
-      render: { sections: [{ title: "run logs", lines: entries }] }
+      render: { sections: [{ title: "run logs", lines: result.entries }] }
     },
     {
       json: argsWantJson(args),
-      text: `${entries.join("\n")}${entries.length > 0 ? "\n" : ""}`
+      text: `${result.entries.join("\n")}${result.entries.length > 0 ? "\n" : ""}`
     }
   );
   return 0;
@@ -11325,6 +12428,34 @@ async function handleRunStop(args) {
   }
   const client = new DeeplineClient();
   const result = await client.runs.stop(runId, { reason });
+  const stopNotConfirmed = result.stopped === false || result.staleSchedulerState === true;
+  if (stopNotConfirmed) {
+    const detail = typeof result.error === "string" && result.error.trim() ? result.error.trim() : result.staleSchedulerState === true ? "scheduler state for the run is stale" : "the server did not confirm the stop";
+    process.stderr.write(
+      `Failed to stop run ${runId}: ${detail}. Retry 'deepline runs stop ${runId}' or inspect the run with 'deepline runs get ${runId} --full --json'.
+`
+    );
+    printCommandEnvelope(
+      {
+        ...result,
+        render: {
+          sections: [
+            {
+              title: "run stop",
+              lines: [
+                `\u2717 stop not confirmed for ${result.runId || runId}`,
+                `  ${detail}`,
+                `  retry: deepline runs stop ${runId}`,
+                `  inspect: deepline runs get ${runId} --full --json`
+              ]
+            }
+          ]
+        }
+      },
+      { json: argsWantJson(args) }
+    );
+    return 1;
+  }
   const lines = [
     `Stopped ${result.runId}`,
     ...result.hitlCancelledCount > 0 ? [`cancelled HITL waits: ${result.hitlCancelledCount}`] : []
@@ -14972,7 +16103,7 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
 }
 function extractionContractEntries(entries) {
   return entries.flatMap((entry) => {
-    if (!isRecord5(entry)) return [];
+    if (!isRecord6(entry)) return [];
     const name = stringField(entry, "name");
     const expression = stringField(entry, "expression");
     return name && expression ? [{ name, expression }] : [];
@@ -14980,8 +16111,8 @@ function extractionContractEntries(entries) {
 }
 function printCompactToolContract(tool, requestedToolId) {
   const contract = toolContractJsonForDescribe(tool, requestedToolId);
-  const cost = isRecord5(contract.cost) ? contract.cost : {};
-  const getters = isRecord5(contract.getters) ? contract.getters : {};
+  const cost = isRecord6(contract.cost) ? contract.cost : {};
+  const getters = isRecord6(contract.getters) ? contract.getters : {};
   const listGetters = Array.isArray(getters.extractedLists) ? getters.extractedLists : [];
   const valueGetters = Array.isArray(getters.extractedValues) ? getters.extractedValues : [];
   const inputFields = Array.isArray(contract.inputFields) ? contract.inputFields : [];
@@ -14998,7 +16129,7 @@ function printCompactToolContract(tool, requestedToolId) {
     console.log("");
     console.log("Inputs:");
     for (const field of inputFields) {
-      if (!isRecord5(field)) continue;
+      if (!isRecord6(field)) continue;
       const name = stringField(field, "name");
       if (!name) continue;
       const required = field.required ? "*" : "";
@@ -15011,7 +16142,7 @@ function printCompactToolContract(tool, requestedToolId) {
   }
   console.log("");
   printToolExamplesOnly(tool, requestedToolId, { includeSamples: false });
-  const starterScript = isRecord5(contract.starterScript) ? contract.starterScript : {};
+  const starterScript = isRecord6(contract.starterScript) ? contract.starterScript : {};
   const starterPath = stringField(starterScript, "path");
   if (starterPath) {
     console.log("");
@@ -15025,14 +16156,14 @@ function printCompactToolContract(tool, requestedToolId) {
     console.log("Getters:");
     if (listGetters.length) console.log("Lists:");
     for (const entry of listGetters) {
-      if (isRecord5(entry))
+      if (isRecord6(entry))
         console.log(
           `- ${stringField(entry, "name")}: ${playResultExpression(entry)}`
         );
     }
     if (valueGetters.length) console.log("Values:");
     for (const entry of valueGetters) {
-      if (isRecord5(entry))
+      if (isRecord6(entry))
         console.log(
           `- ${stringField(entry, "name")}: ${playResultExpression(entry)}`
         );
@@ -15045,7 +16176,7 @@ function printCompactToolContract(tool, requestedToolId) {
 }
 function printToolPricingOnly(tool, requestedToolId, options = {}) {
   const contract = toolContractJsonForDescribe(tool, requestedToolId);
-  const cost = isRecord5(contract.cost) ? contract.cost : {};
+  const cost = isRecord6(contract.cost) ? contract.cost : {};
   const pricingModel = stringField(cost, "pricingModel") || "unknown";
   const billingMode = stringField(cost, "billingMode") || "unknown";
   const unit = pricingModel === "per_page" ? "page" : pricingModel === "per_result" ? "result" : pricingModel === "fixed" ? "call" : pricingModel.replace(/^per_/, "") || "unit";
@@ -15065,7 +16196,7 @@ function printToolSchemaOnly(tool, requestedToolId) {
   }
   console.log("Inputs:");
   for (const field of inputFields) {
-    if (!isRecord5(field)) continue;
+    if (!isRecord6(field)) continue;
     const name = stringField(field, "name");
     if (!name) continue;
     const required = field.required ? "*" : "";
@@ -15091,10 +16222,10 @@ function printToolExamplesOnly(tool, requestedToolId, options = {}) {
     `  input: ${JSON.stringify(sampleInput || {}, null, 2).replace(/\n/g, "\n  ")},`
   );
   console.log("});");
-  const getters = isRecord5(contract.getters) ? contract.getters : {};
+  const getters = isRecord6(contract.getters) ? contract.getters : {};
   const valueGetters = Array.isArray(getters.extractedValues) ? getters.extractedValues : [];
   const listGetters = Array.isArray(getters.extractedLists) ? getters.extractedLists : [];
-  const firstGetter = [...valueGetters, ...listGetters].find(isRecord5);
+  const firstGetter = [...valueGetters, ...listGetters].find(isRecord6);
   if (firstGetter) {
     const name = stringField(firstGetter, "name") || "value";
     const expression = stringField(firstGetter, "expression");
@@ -15111,7 +16242,7 @@ function printToolExamplesOnly(tool, requestedToolId, options = {}) {
 }
 function printToolGettersOnly(tool, requestedToolId) {
   const contract = toolContractJsonForDescribe(tool, requestedToolId);
-  const getters = isRecord5(contract.getters) ? contract.getters : {};
+  const getters = isRecord6(contract.getters) ? contract.getters : {};
   const listGetters = Array.isArray(getters.extractedLists) ? getters.extractedLists : [];
   const valueGetters = Array.isArray(getters.extractedValues) ? getters.extractedValues : [];
   console.log(`Getters: ${contract.toolId}`);
@@ -15124,7 +16255,7 @@ function printToolGettersOnly(tool, requestedToolId) {
   if (listGetters.length) {
     console.log("Lists:");
     for (const entry of listGetters) {
-      if (isRecord5(entry))
+      if (isRecord6(entry))
         console.log(
           `- ${stringField(entry, "name")}: ${playResultExpression(entry)}`
         );
@@ -15133,7 +16264,7 @@ function printToolGettersOnly(tool, requestedToolId) {
   if (valueGetters.length) {
     console.log("Values:");
     for (const entry of valueGetters) {
-      if (isRecord5(entry))
+      if (isRecord6(entry))
         console.log(
           `- ${stringField(entry, "name")}: ${playResultExpression(entry)}`
         );
@@ -15159,7 +16290,7 @@ function sampleValueForField(field) {
 function samplePayloadForInputFields(fields) {
   return Object.fromEntries(
     fields.slice(0, 4).flatMap((field) => {
-      if (!isRecord5(field)) return [];
+      if (!isRecord6(field)) return [];
       const name = stringField(field, "name");
       if (!name) return [];
       return [[name, sampleValueForField(field)]];
@@ -15273,12 +16404,12 @@ function formatListedToolCost(tool) {
 }
 function toolInputFieldsForDisplay(inputSchema) {
   if (Array.isArray(inputSchema.fields))
-    return inputSchema.fields.filter(isRecord5);
-  const jsonSchema = isRecord5(inputSchema.jsonSchema) ? inputSchema.jsonSchema : inputSchema;
-  const properties = isRecord5(jsonSchema.properties) ? jsonSchema.properties : {};
+    return inputSchema.fields.filter(isRecord6);
+  const jsonSchema = isRecord6(inputSchema.jsonSchema) ? inputSchema.jsonSchema : inputSchema;
+  const properties = isRecord6(jsonSchema.properties) ? jsonSchema.properties : {};
   const required = Array.isArray(jsonSchema.required) ? new Set(jsonSchema.required.map(String)) : /* @__PURE__ */ new Set();
   return Object.entries(properties).map(([name, value]) => {
-    const property = isRecord5(value) ? value : {};
+    const property = isRecord6(value) ? value : {};
     return {
       name,
       type: typeof property.type === "string" ? property.type : "unknown",
@@ -15307,15 +16438,15 @@ function printJsonPreview(label, payload) {
 }
 function samplePayload(samples, key) {
   const entry = samples[key];
-  if (!isRecord5(entry)) return void 0;
+  if (!isRecord6(entry)) return void 0;
   return Object.prototype.hasOwnProperty.call(entry, "payload") ? entry.payload : entry;
 }
 function commandEnvelopeFromRawResponse(rawResponse) {
-  return isRecord5(rawResponse) ? { ...rawResponse } : { status: "completed", result: rawResponse };
+  return isRecord6(rawResponse) ? { ...rawResponse } : { status: "completed", result: rawResponse };
 }
 function listExtractorPathsFromUsageGuidance(tool) {
   const toolExecutionResult = tool.usageGuidance?.toolExecutionResult;
-  const extractedLists = Array.isArray(toolExecutionResult?.extractedLists) ? toolExecutionResult.extractedLists : isRecord5(toolExecutionResult?.extractedLists) ? Object.values(toolExecutionResult.extractedLists) : [];
+  const extractedLists = Array.isArray(toolExecutionResult?.extractedLists) ? toolExecutionResult.extractedLists : isRecord6(toolExecutionResult?.extractedLists) ? Object.values(toolExecutionResult.extractedLists) : [];
   return extractedLists.flatMap((entry) => {
     const paths = entry.details?.candidatePaths ?? entry.details?.rawToolOutputPaths;
     if (!Array.isArray(paths)) return [];
@@ -15331,7 +16462,7 @@ function formatDecimal(value) {
 function formatUsd(value) {
   return `$${formatDecimal(value)}`;
 }
-function isRecord5(value) {
+function isRecord6(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function stringField(source, ...keys) {
@@ -15358,7 +16489,7 @@ function arrayField(source, ...keys) {
 function recordField(source, ...keys) {
   for (const key of keys) {
     const value = source[key];
-    if (isRecord5(value)) return value;
+    if (isRecord6(value)) return value;
   }
   return {};
 }
@@ -15424,7 +16555,7 @@ function parseJsonObjectArgument(raw, flagName) {
     }
     throw invalidJsonError(flagName, message);
   }
-  if (!isRecord5(parsed)) {
+  if (!isRecord6(parsed)) {
     throw invalidJsonError(flagName, "expected an object.");
   }
   return parsed;
@@ -15547,7 +16678,7 @@ function buildToolExecuteBaseEnvelope(input2) {
     kind: summaryEntries.length > 0 ? "object" : "raw",
     summary: input2.summary
   };
-  const envelopeHasCanonicalOutput = isRecord5(envelope.toolResponse) && Object.prototype.hasOwnProperty.call(envelope.toolResponse, "raw");
+  const envelopeHasCanonicalOutput = isRecord6(envelope.toolResponse) && Object.prototype.hasOwnProperty.call(envelope.toolResponse, "raw");
   const inspectCommand = `deepline tools execute ${input2.toolId} --input ${shellQuote(JSON.stringify(input2.params))} --json`;
   const actions = input2.listConversion ? [
     {
@@ -15656,7 +16787,7 @@ async function executeTool(args) {
       {
         ...baseEnvelope,
         local: {
-          ...isRecord5(baseEnvelope.local) ? baseEnvelope.local : {},
+          ...isRecord6(baseEnvelope.local) ? baseEnvelope.local : {},
           payload_file: jsonPath
         }
       },