deepline 0.3.212 → 0.3.214

package/dist/bundling-sources/sdk/src/client.ts

@@ -1,3 +1,8 @@
+import type {
+  PlaySettingsResult,
+  PlaySettingsPatch,
+  PlaySettingsPathsPage,
+} from '../../shared_libs/plays/settings-contract';
 import { iterateCursorPages } from './pagination.js';
 import type { ToolResultBilling } from '../../shared_libs/plays/tool-result-types.js';
 /**
@@ -825,6 +830,36 @@ export type RunsGetOptions = {
   failedLogLimit?: number;
 };
 
+export type RunGetStatus =
+  | {
+      available: false;
+      reason: 'not_projected' | 'read_failed';
+    }
+  | {
+      available: true;
+      observedAt: number;
+      source: {
+        ledgerNextSeq: number | null;
+        runSnapshotLedgerNextSeq: number | null;
+        aligned: boolean | null;
+      };
+      calls: {
+        logicalCalls: { value: number | null; confirmed: boolean };
+        toolDispatches: { value: number | null; confirmed: boolean };
+        provider429s: { value: number | null; confirmed: boolean };
+      };
+      focusStep: {
+        id: string;
+        label: string | null;
+        status: string | null;
+        rows: {
+          succeeded: number | null;
+          failed: number | null;
+          total: number | null;
+        };
+      } | null;
+    };
+
 const RUNS_FAILED_LOG_LIMIT = 20;
 
 /** Streaming options for `client.runs.tail(...)`. */
@@ -963,7 +998,10 @@ export type PlaySecretCheck = {
 export type RunsNamespace = {
   /** Get current run status by public run id. */
   get: (runId: string, options?: RunsGetOptions) => Promise<PlayStatus>;
-  /** Read bounded scalar lifecycle and confirmed work counts only. */
+  /**
+   * @deprecated Use `client.runs.get(runId)` for status, progress, logs, and results.
+   * This scalar-only reader remains for compatibility with existing callers.
+   */
   status: (runId: string) => Promise<RunLifecycleStatus>;
   /** Explicitly read the retained original input (may include customer data). */
   input: (runId: string) => Promise<{
@@ -1026,6 +1064,21 @@ export type RunLifecycleStatus =
         startedAt: number | null;
         finishedAt: number | null;
       };
+      /** Null for scheduler-only admission or a pre-expansion projection row. */
+      source?: { ledgerNextSeq: number | null };
+      /** One durable current activity, not proof that every row is blocked. */
+      activity?: {
+        kind: string;
+        reason: string | null;
+        targetKind: string | null;
+        observedAt: number | null;
+        nextAt: number | null;
+      } | null;
+      calls?: {
+        logicalCalls: { value: number | null; confirmed: boolean };
+        providerRequests: { value: number | null; confirmed: boolean };
+        provider429s: { value: number | null; confirmed: boolean };
+      };
       steps: {
         observed: number;
         running: number;
@@ -2479,10 +2532,25 @@ function normalizePlayStatus(raw: Record<string, unknown>): PlayStatus {
       : typeof raw.workflowId === 'string'
         ? raw.workflowId
         : (packageRun?.id ?? '');
+  const legacyOverview = runPackage?.overview ?? raw.overview;
+  const runStatus = runPackage?.runStatus ?? raw.runStatus;
   return {
     ...(raw as unknown as Omit<PlayStatus, 'runId' | 'status'>),
     runId,
-    ...(runPackage ? { package: runPackage, outputs: runPackage.outputs } : {}),
+    ...(isRecord(legacyOverview)
+      ? {
+          overview: legacyOverview as unknown as RunLifecycleStatus,
+        }
+      : {}),
+    ...(isRecord(runStatus)
+      ? { runStatus: runStatus as unknown as RunGetStatus }
+      : {}),
+    ...(runPackage
+      ? {
+          package: runPackage,
+          outputs: runPackage.outputs,
+        }
+      : {}),
     status,
   };
 }
@@ -2835,19 +2903,6 @@ function playRunResultFromStatus(
   };
 }
 
-function playRunStatusFromState(state: PlayLiveStatusState): PlayStatus {
-  return {
-    runId: state.runId,
-    status: state.status,
-    progress: {
-      status: state.status,
-      logs: state.logs,
-      ...(state.error ? { error: state.error } : {}),
-    },
-    ...('result' in state ? { result: state.result } : {}),
-  };
-}
-
 /**
  * Low-level typed REST client with authentication, retries, and localhost failover.
  *
@@ -3332,6 +3387,12 @@ export class DeeplineClient {
       options.includeSearchDebug ? 'true' : 'false',
     );
     params.set('search_mode', options.searchMode ?? 'v2');
+    if (options.limit !== undefined) {
+      params.set('limit', String(options.limit));
+    }
+    if (options.offset !== undefined) {
+      params.set('offset', String(options.offset));
+    }
     if (options.categories?.trim()) {
       params.set('categories', options.categories.trim());
     }
@@ -4792,8 +4853,25 @@ export class DeeplineClient {
     const query = params.size > 0 ? `?${params.toString()}` : '';
     const response = await this.http.get<Record<string, unknown>>(
       `/api/v2/runs/${encodeURIComponent(runId)}${query}`,
+      { headers: { 'x-deepline-run-status': '1' } },
     );
+    const responseRunStatus = isPlayRunPackage(response)
+      ? response.runStatus
+      : isPlayRunPackage(response.package)
+        ? response.package.runStatus
+        : response.runStatus;
+    const responseOverview = isPlayRunPackage(response)
+      ? response.overview
+      : isPlayRunPackage(response.package)
+        ? response.package.overview
+        : response.overview;
     const status = normalizePlayStatus(response);
+    if (isRecord(responseRunStatus)) {
+      status.runStatus = responseRunStatus as unknown as RunGetStatus;
+    }
+    if (isRecord(responseOverview)) {
+      status.overview = responseOverview as unknown as RunLifecycleStatus;
+    }
     if (options?.failedLogs !== true || status.status !== 'failed') {
       return status;
     }
@@ -4844,7 +4922,10 @@ export class DeeplineClient {
     };
   }
 
-  /** Read only the bounded scalar projection; does not hydrate the run package. */
+  /** Fetch only the legacy scalar lifecycle status for a run.
+   *
+   * @deprecated Use `client.runs.get(runId)` for the canonical run read.
+   */
   async getRunLifecycleStatus(runId: string): Promise<RunLifecycleStatus> {
     const response = await this.http.get<RunLifecycleStatus>(
       `/api/v2/runs/${encodeURIComponent(runId)}/status`,
@@ -5052,9 +5133,7 @@ export class DeeplineClient {
       if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {
         continue;
       }
-      return await this.getRunStatus(status.runId || runId).catch(
-        () => state.latest ?? playRunStatusFromState(state),
-      );
+      return await this.getRunStatus(status.runId || runId);
     }
     if (options?.signal?.aborted) {
       throw new DeeplineError('Run observation aborted.', undefined, 'ABORTED');
@@ -5110,6 +5189,7 @@ export class DeeplineClient {
     for (;;) {
       const connectedAt = Date.now();
       let sawEvent = false;
+      let terminalRunId: string | null = null;
       let endedReason = 'stream window ended before a terminal event';
       try {
         for await (const event of this.streamPlayRunEvents(runId, {
@@ -5122,9 +5202,8 @@ export class DeeplineClient {
           if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {
             continue;
           }
-          return await this.getRunStatus(status.runId || runId).catch(
-            () => state.latest ?? playRunStatusFromState(state),
-          );
+          terminalRunId = status.runId || runId;
+          break;
         }
       } catch (error) {
         if (options?.signal?.aborted || !isTransientPlayStreamError(error)) {
@@ -5133,18 +5212,16 @@ export class DeeplineClient {
         endedReason = error instanceof Error ? error.message : String(error);
       }
 
+      if (terminalRunId) {
+        return await this.getRunStatus(terminalRunId);
+      }
+
       // Window ended without a terminal event. The run may have finished
       // during the gap — re-check durable status once before reconnecting.
-      // Non-transient status failures (e.g. 404 = run gone) fail loudly.
-      let refreshed: PlayStatus | null = null;
-      try {
-        refreshed = await this.getRunStatus(runId);
-      } catch (error) {
-        if (!isTransientPlayStreamError(error)) {
-          throw error;
-        }
-      }
-      if (refreshed && TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
+      // `runs.get` owns the durable snapshot; its optional status evidence is
+      // additive and must not prevent old servers from ending this stream.
+      const refreshed = await this.getRunStatus(runId);
+      if (TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
         return refreshed;
       }
 
@@ -5536,6 +5613,34 @@ export class DeeplineClient {
     };
   }
 
+  /** Read definition-level settings, independently of code revisions. */
+  async getPlaySettings(playName: string): Promise<PlaySettingsResult> {
+    return this.http.get(
+      `/api/v2/plays/${encodeURIComponent(playName)}/settings`,
+    );
+  }
+
+  /** Retry-safe field patch; omitted fields retain their current value. */
+  async updatePlaySettings(
+    playName: string,
+    patch: PlaySettingsPatch,
+  ): Promise<PlaySettingsResult> {
+    return this.http.patch(
+      `/api/v2/plays/${encodeURIComponent(playName)}/settings`,
+      patch,
+    );
+  }
+
+  /** List one bounded page of existing Play locations; continue with cursor. */
+  async listPlaySettingsPaths(
+    options: { root?: 'person' | 'team'; limit?: number; cursor?: string } = {},
+  ): Promise<PlaySettingsPathsPage> {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(options))
+      if (value !== undefined) query.set(key, String(value));
+    return this.http.get(`/api/v2/plays/settings/paths?${query}`);
+  }
+
   /** Set whether an org-owned Play sorts before unpinned Plays. */
   async setPlayPinned(
     playName: string,

package/dist/bundling-sources/sdk/src/compat.ts

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { sdkCliStateDirPath } from './config.js';
+import { deploymentProtectionHeaders } from './deployment-protection.js';
 
 export type SdkCompatibilityStatus =
   | 'current'
@@ -334,6 +335,7 @@ export async function checkSdkCompatibility(
     const response = await fetch(url, {
       method: 'GET',
       headers: {
+        ...deploymentProtectionHeaders(),
         'User-Agent': `deepline-ts-sdk/${SDK_VERSION}`,
         'X-Deepline-SDK-Version': SDK_VERSION,
         'X-Deepline-API-Major': String(SDK_API_MAJOR),

package/dist/bundling-sources/sdk/src/deployment-protection.ts

@@ -0,0 +1,19 @@
+/** Headers shared by SDK requests and the CLI's directory deployment body. */
+export function deploymentProtectionHeaders(): Record<string, string> {
+  const token =
+    typeof process !== 'undefined'
+      ? process.env?.VERCEL_PROTECTION_BYPASS_TOKEN
+      : undefined;
+  return token ? { 'x-vercel-protection-bypass': token } : {};
+}
+
+export const fetchWithDeploymentProtection: typeof fetch = (input, init) => {
+  const headers = new Headers(
+    input instanceof Request ? input.headers : undefined,
+  );
+  new Headers(init?.headers).forEach((value, name) => headers.set(name, value));
+  for (const [name, value] of Object.entries(deploymentProtectionHeaders())) {
+    headers.set(name, value);
+  }
+  return fetch(input, { ...init, headers });
+};

package/dist/bundling-sources/sdk/src/http.ts

@@ -35,6 +35,7 @@ import { SDK_API_CONTRACT, SDK_VERSION } from './version.js';
 import type { LiveEventEnvelope } from './types.js';
 import { detectAgentRuntime, isCoworkLikeSandbox } from './agent-runtime.js';
 import { readSdkSkillsLocalVersion } from './skills-version.js';
+import { deploymentProtectionHeaders } from './deployment-protection.js';
 import {
   ABSURD_RELEASE_OVERRIDE_HEADER,
   COORDINATOR_INTERNAL_TOKEN_HEADER,
@@ -266,18 +267,12 @@ export class HttpClient {
       'X-Deepline-API-Contract': SDK_API_CONTRACT,
       'X-Deepline-Run-Result-Shape': 'canonical',
       ...extra,
+      ...deploymentProtectionHeaders(),
     };
     const skillsVersion = this.readSkillsVersionHeader();
     if (skillsVersion) {
       headers['X-Deepline-Skills-Version'] = skillsVersion;
     }
-    const bypassToken =
-      typeof process !== 'undefined'
-        ? process.env?.VERCEL_PROTECTION_BYPASS_TOKEN
-        : undefined;
-    if (bypassToken) {
-      headers['x-vercel-protection-bypass'] = bypassToken;
-    }
     const playArtifactR2Prefix =
       typeof process !== 'undefined'
         ? process.env?.DEEPLINE_PLAY_ARTIFACT_R2_PREFIX
@@ -706,6 +701,7 @@ export class HttpClient {
       | 'onResponse'
       | 'allowNotFound'
       | 'idempotencyKey'
+      | 'headers'
     >,
   ): Promise<T> {
     return this.request<T>(path, {

package/dist/bundling-sources/sdk/src/index.ts

@@ -1,3 +1,10 @@
+export type {
+  PlaySettings,
+  PlayPath,
+  PlaySettingsPatch,
+  PlaySettingsResult,
+  PlaySettingsPathsPage,
+} from '../../shared_libs/plays/settings-contract';
 /**
  * Deepline SDK — TypeScript client for the Deepline enrichment platform.
  *

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.212',
+  version: '0.3.214',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/sdk/src/types.ts

@@ -1,4 +1,6 @@
+import type { PlaySettings } from '../../shared_libs/plays/settings-contract';
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest';
+import type { RunGetStatus, RunLifecycleStatus } from './client.js';
 import type { PlayGrepMatch } from '../../shared_libs/plays/play-grep-search';
 import type { PlayRuntimeSelection } from '../../shared_libs/play-runtime/runtime-environment';
 import type {
@@ -466,6 +468,10 @@ export type InferenceQuote = {
 export interface ToolSearchOptions {
   /** Free-text search query. */
   query?: string;
+  /** Maximum number of ranked tools to return (1-50; defaults to 20). */
+  limit?: number;
+  /** Zero-based offset into the ranked result set. */
+  offset?: number;
   /** Comma-separated category filter such as `company_search` or `email_finder`. */
   categories?: string;
   /** Optional explicit search terms used by agent/CLI callers. */
@@ -488,6 +494,12 @@ export interface ToolSearchResult {
   count?: number;
   /** Matching count within the selected retrieval set. Check total_is_exact. */
   total?: number;
+  /** Zero-based offset used for this page. */
+  offset?: number;
+  /** Maximum number of ranked tools requested for this page. */
+  limit?: number;
+  /** Offset to pass for the next page, when more results are in this result set. */
+  next_offset?: number;
   /** False when indexed retrieval uses a bounded candidate set. */
   total_is_exact?: boolean;
   /** True when indexed retrieval may have additional matching tools. */
@@ -729,6 +741,12 @@ export interface PlayRunPackage {
   schemaVersion: 1;
   /** Package discriminator. */
   kind: 'play_run';
+  /** Ledger position of the detailed snapshot, when provided by this server. */
+  source?: { ledgerNextSeq: number | null };
+  /** Legacy status evidence returned by older servers. */
+  overview?: RunLifecycleStatus;
+  /** Optional bounded live evidence from the existing run status projection. */
+  runStatus?: RunGetStatus;
   /** Run identity, status, timing, and dashboard metadata. */
   run: {
     id: string;
@@ -834,6 +852,10 @@ export type PlayRunOutcome =
 export interface PlayStatus {
   /** Public play-run identifier. */
   runId: string;
+  /** Legacy status evidence returned by older servers. */
+  overview?: RunLifecycleStatus;
+  /** Additive bounded evidence when returned by the current server. */
+  runStatus?: RunGetStatus;
   /** Public Deepline play-run API version. */
   apiVersion?: number;
   /** Saved play name for this run, when available. */
@@ -1310,6 +1332,8 @@ export interface PlaySheetSummary {
  * Returned by {@link DeeplineClient.getPlay}.
  */
 export interface PlayDefinitionDetail {
+  /** Definition settings; never attached to a revision. */
+  settings?: PlaySettings;
   /** Convex document ID. */
   _id: string;
   /** Stable registry key. */
@@ -1415,6 +1439,7 @@ export type PlayCostEstimate =
     };
 
 export interface PlayListItem {
+  settings?: PlaySettings;
   playKey?: string;
   reference?: string;
   name: string;

package/dist/bundling-sources/shared_libs/observability/scheduled-jobs.json

@@ -939,6 +939,24 @@
     "failureAlert": "convex_action_wrapper",
     "domainReportRequired": true
   },
+  {
+    "id": "convex.refresh-tool-usage-popularity",
+    "name": "Refresh tool usage popularity",
+    "scheduler": "convex_cron",
+    "cadence": "37 0 * * *",
+    "timezone": "UTC",
+    "source": "packages/convex/crons.ts",
+    "locator": "refresh tool usage popularity snapshot",
+    "owner": "integrations",
+    "criticality": "operational",
+    "purpose": "Sum distinct user-days per tool over the last 28 complete UTC days into the snapshot tools search uses as a ranking prior, then delete user-day rows past retention.",
+    "successDefinition": "A new snapshot row is written and expired user-day rows are drained; an empty snapshot is valid before any usage is folded.",
+    "failureDefinition": "Reading daily counts, writing the snapshot, or draining expired rows fails, leaving search on the previous snapshot.",
+    "startGraceMs": 120000,
+    "runTimeoutMs": 1800000,
+    "failureAlert": "convex_action_wrapper",
+    "domainReportRequired": true
+  },
   {
     "id": "convex.salesforce-oauth-refresh-maintenance",
     "name": "Maintain Salesforce OAuth refresh tokens",

package/dist/bundling-sources/shared_libs/observability/scheduled-work-manual.ts

@@ -14,6 +14,7 @@ export const MANUALLY_RUNNABLE_CONVEX_CRON_JOB_IDS = [
   'convex.cleanup-expired-api-key-claims',
   'convex.cleanup-expired-analytics-ip2company-cache',
   'convex.cleanup-expired-domain-health-cache',
+  'convex.refresh-tool-usage-popularity',
   'convex.salesforce-oauth-refresh-maintenance',
   'convex.monitor-fleet-convergence-tick',
   'convex.monitor-provider-repair-recovery-tick',

package/dist/bundling-sources/shared_libs/play-runtime/deployment/fly-registry.ts

@@ -2,6 +2,8 @@ import { spawnSync } from 'node:child_process';
 
 const FLY_REGISTRY_COMMAND_TIMEOUT_MS = 30_000;
 const RUNTIME_IMAGE_MANIFEST_TIMEOUT_MS = 10_000;
+export const FLY_REGISTRY_MANIFEST_ATTEMPTS = 3;
+const FLY_REGISTRY_MANIFEST_RETRY_DELAY_MS = 1_500;
 
 type FlyRegistryCommandResult = Readonly<{
   error?: Error & { code?: string };
@@ -59,15 +61,39 @@ export function runtimeImageManifestExists(
   options: {
     timeoutMs?: number;
     spawnCommand?: FlyRegistryCommandSpawn;
+    sleep?: (ms: number) => void;
   } = {},
 ): boolean {
-  return run(
-    'docker',
-    ['manifest', 'inspect', image],
-    true,
-    options.timeoutMs ?? RUNTIME_IMAGE_MANIFEST_TIMEOUT_MS,
-    options.spawnCommand,
-  );
+  const timeoutMs = options.timeoutMs ?? RUNTIME_IMAGE_MANIFEST_TIMEOUT_MS;
+  const sleep = options.sleep ?? sleepSync;
+  for (
+    let attempt = 1;
+    attempt <= FLY_REGISTRY_MANIFEST_ATTEMPTS;
+    attempt += 1
+  ) {
+    try {
+      return run(
+        'docker',
+        ['manifest', 'inspect', image],
+        true,
+        timeoutMs,
+        options.spawnCommand,
+      );
+    } catch (error) {
+      if (
+        !(error instanceof Error) ||
+        (error as NodeJS.ErrnoException).code !== 'ETIMEDOUT' ||
+        attempt === FLY_REGISTRY_MANIFEST_ATTEMPTS
+      ) {
+        throw error;
+      }
+      console.warn(
+        `${error.message} Retrying manifest probe (${attempt}/${FLY_REGISTRY_MANIFEST_ATTEMPTS}).`,
+      );
+      sleep(FLY_REGISTRY_MANIFEST_RETRY_DELAY_MS * attempt);
+    }
+  }
+  throw new Error('Fly registry manifest probe exhausted without a result.');
 }
 
 export const FLY_REGISTRY_AUTH_ATTEMPTS = 3;

package/dist/bundling-sources/shared_libs/play-runtime/runner-app/index.ts

@@ -3614,8 +3614,15 @@ async function main() {
         process.exit(1);
       },
     });
+    // The Daytona watchdog is a separate process and can keep runner liveness
+    // advancing while synchronous customer JavaScript occupies this process's
+    // event loop. Hand off only after the existing durable `waiting` fence and
+    // immediately before the marker that starts customer execution.
+    const lastHeartbeatAtMs = heartbeat?.lastSuccessAtMs();
+    heartbeat?.stop();
     writeRunnerRuntimeStartedMarker(
       process.env.DEEPLINE_PLAY_RUNNER_RUNTIME_STARTED_PATH,
+      lastHeartbeatAtMs === undefined ? {} : { lastHeartbeatAtMs },
     );
     let result: PlayRunnerResult | null = null;
     let executionFailed = false;
@@ -3791,7 +3798,7 @@ export async function materializeTransportedArtifactWhileRunnerParks(
 
 export function writeRunnerRuntimeStartedMarker(
   path: string | null | undefined,
-  detail: { pid?: number; at?: number } = {},
+  detail: { pid?: number; at?: number; lastHeartbeatAtMs?: number } = {},
 ): void {
   const runtimeStartedPath = path?.trim();
   if (!runtimeStartedPath) return;
@@ -3801,6 +3808,9 @@ export function writeRunnerRuntimeStartedMarker(
       started: true,
       pid: detail.pid ?? process.pid,
       at: detail.at ?? Date.now(),
+      ...(typeof detail.lastHeartbeatAtMs === 'number'
+        ? { lastHeartbeatAtMs: detail.lastHeartbeatAtMs }
+        : {}),
     }),
     'utf-8',
   );

package/dist/bundling-sources/shared_libs/play-runtime/runner-app/runtime-heartbeat.ts

@@ -100,6 +100,8 @@ export interface RunnerHeartbeatLoopHandle {
   executionAcknowledged: Promise<void>;
   /** Trigger an immediate heartbeat while waiting for the park acknowledgement. */
   requestHeartbeat: () => void;
+  /** Last durable heartbeat timestamp, used for an external liveness handoff. */
+  lastSuccessAtMs: () => number;
 }
 
 const APP_RUNTIME_COMPAT_PATH = '/api/v2/plays/runtime';
@@ -420,5 +422,6 @@ export function startRunnerHeartbeatLoop(
     firstHeartbeat,
     executionAcknowledged,
     requestHeartbeat: tick,
+    lastSuccessAtMs: () => lastSuccessAt,
   };
 }

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-payload-transport.ts

@@ -27,6 +27,7 @@ import {
   RUNTIME_SANDBOX_MEMORY_ABORT_CODE,
   RUNTIME_SANDBOX_MEMORY_ABORT_MESSAGE,
   RUNTIME_SANDBOX_OOM_MESSAGE,
+  RUNTIME_CONTROL_PLANE_UNAVAILABLE_MESSAGE,
 } from '../../run-failure';
 import {
   buildDaytonaPayloadMaterializerSource,
@@ -293,6 +294,41 @@ function watchdogMemoryAbortDiagnostic() {
   return null;
 }
 
+function watchdogRunnerHeartbeatUnavailableDiagnostic() {
+  try {
+    if (!terminationDiagnosticPath) return null;
+    const diagnostic = JSON.parse(
+      fs.readFileSync(terminationDiagnosticPath, 'utf8'),
+    );
+    if (
+      !diagnostic ||
+      diagnostic.schemaVersion !== 1 ||
+      diagnostic.reason !== 'runner_heartbeat_unreachable'
+    ) {
+      return null;
+    }
+    return {
+      heartbeatAttempt: Number.isSafeInteger(diagnostic.heartbeatAttempt)
+        ? diagnostic.heartbeatAttempt
+        : null,
+      heartbeatAgeMs: Number.isFinite(diagnostic.heartbeatAgeMs)
+        ? Math.max(0, diagnostic.heartbeatAgeMs)
+        : null,
+      leaseMs: Number.isFinite(diagnostic.leaseMs)
+        ? Math.max(0, diagnostic.leaseMs)
+        : null,
+      lastErrorCode:
+        typeof diagnostic.lastErrorCode === 'string' &&
+        /^(?:E[A-Z0-9_]+|ERR_[A-Z0-9_]+|UND_ERR_[A-Z0-9_]+|TimeoutError|redirect_[0-9]{3}|http_[0-9]{3}|protocol_error|unknown)$/.test(
+          diagnostic.lastErrorCode,
+        )
+          ? diagnostic.lastErrorCode
+          : 'unknown',
+    };
+  } catch {}
+  return null;
+}
+
 function memoryAbortCause(diagnostic) {
   const parts = [
     ${JSON.stringify(`${RUNTIME_SANDBOX_MEMORY_ABORT_CODE}: ${RUNTIME_SANDBOX_MEMORY_ABORT_MESSAGE}`)},
@@ -373,6 +409,7 @@ async function main() {
   // SIGKILL does not collapse into the wrapper's generic exit code 1.
   const sandboxKilled = exitCode === 137 || watchdogObservedChildSigkill();
   const memoryAbort = watchdogMemoryAbortDiagnostic();
+  const heartbeatUnavailable = watchdogRunnerHeartbeatUnavailableDiagnostic();
   const sandboxOom =
     !memoryAbort &&
     sandboxKilled &&
@@ -383,6 +420,10 @@ async function main() {
       ? memoryAbortCause(memoryAbort)
     : sandboxOom
       ? 'RUNTIME_SANDBOX_OOM: ' + ${JSON.stringify(RUNTIME_SANDBOX_OOM_MESSAGE)}
+    : heartbeatUnavailable
+      ? 'RUNTIME_CONTROL_PLANE_UNAVAILABLE: ' +
+        ${JSON.stringify(RUNTIME_CONTROL_PLANE_UNAVAILABLE_MESSAGE)} +
+        ' heartbeat=' + JSON.stringify(heartbeatUnavailable)
       : sandboxKilled
         ? 'RUNTIME_SANDBOX_KILLED: ' + ${JSON.stringify(RUNTIME_SANDBOX_KILLED_MESSAGE)}
     :
@@ -408,6 +449,15 @@ async function main() {
           message: ${JSON.stringify(RUNTIME_SANDBOX_MEMORY_ABORT_MESSAGE)},
           retryable: false,
           cause: synthesizedError,
+      }] }
+      : {}),
+    ...(heartbeatUnavailable && !runtimeLimitExceeded && !memoryAbort && !sandboxOom
+      ? { errors: [{
+          code: 'RUNTIME_CONTROL_PLANE_UNAVAILABLE',
+          phase: 'infrastructure',
+          message: ${JSON.stringify(RUNTIME_CONTROL_PLANE_UNAVAILABLE_MESSAGE)},
+          retryable: false,
+          cause: synthesizedError,
         }] }
       : {}),
     ...(sandboxOom
@@ -428,7 +478,9 @@ async function main() {
           cause: synthesizedError,
         }] }
       : {}),
-    logs: [],
+    logs: heartbeatUnavailable
+      ? ['[runtime.failure_diagnostic] ' + JSON.stringify({ event: 'runner_heartbeat_unavailable', ...heartbeatUnavailable })]
+      : [],
     stats: {},
     steps: [],
     checkpointDisposition: '${RUNNER_TERMINAL_CHECKPOINT_DISPOSITION.ABSENT}',