@shipfox/api-runners 12.3.0 → 12.4.0

package/src/db/runner-instances.ts

@@ -17,15 +17,20 @@ import {
   sql,
 } from 'drizzle-orm';
 import {alias} from 'drizzle-orm/pg-core';
+import {config} from '#config.js';
 import type {RunnerInstance, RunnerInstanceState} from '#core/entities/runner-instance.js';
 import {sanitizeRunnerLabels} from '#core/runner-labels.js';
+import {recordRunnerReservationCapacityFailure} from '#metrics/index.js';
 import type {Tx} from './db.js';
 import {db} from './db.js';
 import {
   listRunningJobExecutionsByRunnerInstanceTx,
   type RunnerInstanceBoundJobExecution,
 } from './job-executions.js';
+import {lockRunnerReservationAdvisoryKeysTx} from './reservation-locks.js';
 import {releaseReservationUnits} from './reservations.js';
+import {validateRunnerReservationCapacityTx} from './runner-assignments.js';
+import {terminalStates} from './runner-states.js';
 import {ephemeralRegistrationTokens} from './schema/ephemeral-registration-tokens.js';
 import {provisionerTokens} from './schema/provisioner-tokens.js';
 import {reservations} from './schema/reservations.js';
@@ -34,11 +39,6 @@ import {providerRunners, toRunnerInstance} from './schema/runner-instances.js';
 import {runnerSessions} from './schema/runner-sessions.js';
 import {runningJobExecutions} from './schema/running-job-executions.js';
 
-export const terminalStates = [
-  'stopped',
-  'failed',
-  'terminated',
-] as const satisfies readonly RunnerInstanceState[];
 export const activeStates = [
   'starting',
   'running',
@@ -49,11 +49,12 @@ export const divergenceCountStates = ['starting', 'running'] as const satisfies
   'starting' | 'running'
 >[];
 
-export type RunnerInstanceTerminateIntentReason = 'job-cancelled';
+export type RunnerInstanceTerminateIntentReason = 'activation-timeout' | 'job-cancelled';
 
 export interface RunnerInstanceTerminateIntent {
   providerRunnerId: string;
   reason: RunnerInstanceTerminateIntentReason;
+  activationTimeoutRetry?: boolean;
 }
 
 export interface ActiveRunnerInstanceTemplateCount {
@@ -155,13 +156,14 @@ export async function reportRunnerInstances(params: ReportRunnerInstancesParams)
     }
 
     const events = await hydrateRunnerSessionIdsFromConsumedTokens(tx, params, aggregatedEvents);
+    const reservationSafeEvents = await guardReportedReservationIdsTx(tx, params, events);
     const terminateIntentsHonored = await listTerminateIntentsHonoredByTerminatedReportsTx(
       tx,
       params,
-      events,
+      reservationSafeEvents,
     );
 
-    const values = events.map((event) => ({
+    const values = reservationSafeEvents.map((event) => ({
       workspaceId: params.workspaceId,
       provisionerId: params.provisionerId,
       providerRunnerId: event.providerRunnerId,
@@ -213,10 +215,105 @@ export async function reportRunnerInstances(params: ReportRunnerInstancesParams)
       });
 
     const reservationsReleased = hasTerminalEvent
-      ? await releaseTerminalRunnerInstanceReservations(tx, params, events)
+      ? await releaseTerminalRunnerInstanceReservations(tx, params, reservationSafeEvents)
       : 0;
 
-    return {accepted: events.length, reservationsReleased, terminateIntentsHonored};
+    return {
+      accepted: reservationSafeEvents.length,
+      reservationsReleased,
+      terminateIntentsHonored,
+    };
+  });
+}
+
+async function guardReportedReservationIdsTx(
+  tx: Tx,
+  params: ReportRunnerInstancesParams,
+  events: RunnerInstanceReportRow[],
+): Promise<RunnerInstanceReportRow[]> {
+  const reservationIds = [
+    ...new Set(events.flatMap((event) => (event.reservationId ? [event.reservationId] : []))),
+  ].sort();
+  if (reservationIds.length === 0) return events;
+
+  await lockRunnerReservationAdvisoryKeysTx(tx, {
+    provisionerId: params.provisionerId,
+    reservationIds,
+  });
+  const providerRunnerIds = events.map((event) => event.providerRunnerId);
+  const existingRows = await tx
+    .select({
+      providerRunnerId: providerRunners.providerRunnerId,
+      reservationId: providerRunners.reservationId,
+      intendedReservationId: providerRunners.intendedReservationId,
+      reservationReleasedAt: providerRunners.reservationReleasedAt,
+    })
+    .from(providerRunners)
+    .where(
+      and(
+        eq(providerRunners.provisionerId, params.provisionerId),
+        inArray(providerRunners.providerRunnerId, providerRunnerIds),
+      ),
+    )
+    .for('update');
+  const existingByProviderRunnerId = new Map(
+    existingRows.flatMap((row) =>
+      row.providerRunnerId ? [[row.providerRunnerId, row] as const] : [],
+    ),
+  );
+  const candidateReservationByProviderRunnerId = new Map<string, string>();
+  for (const event of events) {
+    if (!event.reservationId) continue;
+    if (isTerminalState(event.state)) continue;
+    const existing = existingByProviderRunnerId.get(event.providerRunnerId);
+    if (existing?.reservationId || existing?.intendedReservationId === event.reservationId)
+      continue;
+    if (existing?.intendedReservationId || existing?.reservationReleasedAt) continue;
+    candidateReservationByProviderRunnerId.set(event.providerRunnerId, event.reservationId);
+  }
+
+  const validation = await validateRunnerReservationCapacityTx(
+    tx,
+    {
+      provisionerId: params.provisionerId,
+      requests: [...candidateReservationByProviderRunnerId.values()].map((reservationId) => ({
+        reservationId,
+        count: 1,
+      })),
+    },
+    {advisoryLocksHeld: true},
+  );
+  for (const {reason, count} of validation.unavailableByReservation.values())
+    recordRunnerReservationCapacityFailure(reason, count);
+
+  const remainingAcceptedByReservation = new Map(validation.acceptedByReservation);
+  return events.map((event) => {
+    const existing = existingByProviderRunnerId.get(event.providerRunnerId);
+    const reservationId = candidateReservationByProviderRunnerId.get(event.providerRunnerId);
+    if (!reservationId) {
+      if (event.reservationId && isTerminalState(event.state)) {
+        // Terminal cleanup releases the IDs stored on the projection row. An arbitrary
+        // terminal report must not consume reservation capacity during that cleanup.
+        const matchesExistingReservation =
+          existing !== undefined &&
+          (existing.reservationId === event.reservationId ||
+            existing.intendedReservationId === event.reservationId);
+        if (!matchesExistingReservation) return {...event, reservationId: null};
+      }
+      if (
+        event.reservationId &&
+        existing?.intendedReservationId &&
+        existing.intendedReservationId !== event.reservationId
+      )
+        return {...event, reservationId: null};
+      if (event.reservationId && existing?.reservationReleasedAt)
+        return {...event, reservationId: null};
+      return event;
+    }
+    const remaining = remainingAcceptedByReservation.get(reservationId) ?? 0;
+    if (remaining === 0) return {...event, reservationId: null};
+    remainingAcceptedByReservation.set(reservationId, remaining - 1);
+    return event;
   });
 }
 
@@ -336,9 +433,42 @@ export async function listProvisionerTerminateIntentRowsTx(
     );
   }
 
-  return returnedRows.flatMap((row) =>
-    row.providerRunnerId ? [{...row, providerRunnerId: row.providerRunnerId}] : [],
+  const activationTimeoutRunnerIds = returnedRows.flatMap((row) =>
+    row.reason === 'activation-timeout' && row.providerRunnerId ? [row.providerRunnerId] : [],
   );
+  if (activationTimeoutRunnerIds.length > 0) {
+    await tx
+      .update(providerRunners)
+      .set({reservationReleasedAt: sql`now()`, updatedAt: sql`now()`})
+      .where(
+        and(
+          eq(providerRunners.workspaceId, params.workspaceId),
+          eq(providerRunners.provisionerId, params.provisionerId),
+          inArray(providerRunners.providerRunnerId, activationTimeoutRunnerIds),
+          isNull(providerRunners.reservationReleasedAt),
+        ),
+      );
+  }
+
+  return returnedRows.flatMap((row) => toRunnerInstanceTerminateIntent(row));
+}
+
+function toRunnerInstanceTerminateIntent(row: {
+  providerRunnerId: string | null;
+  reason: RunnerInstanceTerminateIntentReason;
+  activationTimeoutRetry: boolean;
+}): RunnerInstanceTerminateIntent[] {
+  if (!row.providerRunnerId) return [];
+
+  return [
+    {
+      providerRunnerId: row.providerRunnerId,
+      reason: row.reason,
+      ...(row.reason === 'activation-timeout' && row.activationTimeoutRetry
+        ? {activationTimeoutRetry: true}
+        : {}),
+    },
+  ];
 }
 
 function provisionerTerminateIntentsQuery(
@@ -346,59 +476,91 @@ function provisionerTerminateIntentsQuery(
   params: {workspaceId: string; provisionerId: string; providerRunnerIds?: string[]},
 ) {
   const newerRunningJobExecutions = alias(runningJobExecutions, 'newer_running_jobs');
+  const latestCancelledJob = exists(
+    tx
+      .select({id: runningJobExecutions.id})
+      .from(runningJobExecutions)
+      .where(
+        and(
+          eq(runningJobExecutions.workspaceId, params.workspaceId),
+          eq(runningJobExecutions.provisionerId, params.provisionerId),
+          eq(runningJobExecutions.providerRunnerId, providerRunners.providerRunnerId),
+          isNotNull(runningJobExecutions.cancellationRequestedAt),
+          notExists(
+            tx
+              .select({id: newerRunningJobExecutions.id})
+              .from(newerRunningJobExecutions)
+              .where(
+                and(
+                  eq(newerRunningJobExecutions.workspaceId, runningJobExecutions.workspaceId),
+                  eq(newerRunningJobExecutions.provisionerId, runningJobExecutions.provisionerId),
+                  eq(
+                    newerRunningJobExecutions.providerRunnerId,
+                    runningJobExecutions.providerRunnerId,
+                  ),
+                  or(
+                    gt(newerRunningJobExecutions.startedAt, runningJobExecutions.startedAt),
+                    and(
+                      eq(newerRunningJobExecutions.startedAt, runningJobExecutions.startedAt),
+                      gt(
+                        newerRunningJobExecutions.jobExecutionId,
+                        runningJobExecutions.jobExecutionId,
+                      ),
+                    ),
+                  ),
+                ),
+              ),
+          ),
+        ),
+      ),
+  );
+  const activationTimeout = and(
+    eq(providerRunners.launchKind, 'demand'),
+    isNull(providerRunners.runnerSessionId),
+    lt(
+      providerRunners.createdAt,
+      sql`now() - (${config.RUNNER_DEMAND_ACTIVATION_TIMEOUT_SECONDS} || ' seconds')::interval`,
+    ),
+    notExists(
+      tx
+        .select({id: reservations.id})
+        .from(reservations)
+        .where(
+          and(
+            or(
+              eq(reservations.id, providerRunners.reservationId),
+              eq(reservations.id, providerRunners.intendedReservationId),
+            ),
+            eq(reservations.workspaceId, params.workspaceId),
+            eq(reservations.provisionerId, params.provisionerId),
+            gt(reservations.expiresAt, sql`now()`),
+          ),
+        ),
+    ),
+  );
 
   return tx
     .select({
       providerRunnerId: providerRunners.providerRunnerId,
-      reason: sql<RunnerInstanceTerminateIntentReason>`'job-cancelled'`,
+      activationTimeoutRetry: sql<boolean>`${providerRunners.reservationReleasedAt} is not null`,
+      reason: sql<RunnerInstanceTerminateIntentReason>`case
+        when ${activationTimeout} then 'activation-timeout'
+        else 'job-cancelled'
+      end`,
     })
-    .from(runningJobExecutions)
-    .innerJoin(
-      providerRunners,
-      and(
-        eq(providerRunners.workspaceId, runningJobExecutions.workspaceId),
-        eq(providerRunners.provisionerId, runningJobExecutions.provisionerId),
-        eq(providerRunners.providerRunnerId, runningJobExecutions.providerRunnerId),
-      ),
-    )
+    .from(providerRunners)
     .where(
       and(
-        eq(runningJobExecutions.workspaceId, params.workspaceId),
-        eq(runningJobExecutions.provisionerId, params.provisionerId),
+        eq(providerRunners.workspaceId, params.workspaceId),
+        eq(providerRunners.provisionerId, params.provisionerId),
         isNotNull(providerRunners.providerRunnerId),
-        isNotNull(runningJobExecutions.cancellationRequestedAt),
         inArray(providerRunners.state, activeStates),
         params.providerRunnerIds && params.providerRunnerIds.length > 0
           ? inArray(providerRunners.providerRunnerId, params.providerRunnerIds)
           : undefined,
-        notExists(
-          tx
-            .select({id: newerRunningJobExecutions.id})
-            .from(newerRunningJobExecutions)
-            .where(
-              and(
-                eq(newerRunningJobExecutions.workspaceId, runningJobExecutions.workspaceId),
-                eq(newerRunningJobExecutions.provisionerId, runningJobExecutions.provisionerId),
-                eq(
-                  newerRunningJobExecutions.providerRunnerId,
-                  runningJobExecutions.providerRunnerId,
-                ),
-                or(
-                  gt(newerRunningJobExecutions.startedAt, runningJobExecutions.startedAt),
-                  and(
-                    eq(newerRunningJobExecutions.startedAt, runningJobExecutions.startedAt),
-                    gt(
-                      newerRunningJobExecutions.jobExecutionId,
-                      runningJobExecutions.jobExecutionId,
-                    ),
-                  ),
-                ),
-              ),
-            ),
-        ),
+        or(latestCancelledJob, activationTimeout),
       ),
-    )
-    .groupBy(providerRunners.providerRunnerId);
+    );
 }
 
 async function listTerminateIntentsHonoredByTerminatedReportsTx(
@@ -419,9 +581,7 @@ async function listTerminateIntentsHonoredByTerminatedReportsTx(
     provisionerId: params.provisionerId,
     providerRunnerIds: terminatedRunnerInstanceIds,
   }).orderBy(asc(providerRunners.providerRunnerId));
-  return rows.flatMap((row) =>
-    row.providerRunnerId ? [{...row, providerRunnerId: row.providerRunnerId}] : [],
-  );
+  return rows.flatMap((row) => toRunnerInstanceTerminateIntent(row));
 }
 
 export async function reconcileRunnerInstances(

package/src/db/runner-states.ts

@@ -0,0 +1,7 @@
+import type {RunnerInstanceState} from '#core/entities/runner-instance.js';
+
+export const terminalStates = [
+  'stopped',
+  'failed',
+  'terminated',
+] as const satisfies readonly RunnerInstanceState[];

package/src/db/schema/reservations.ts

@@ -1,9 +1,11 @@
 import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
 import {sql} from 'drizzle-orm';
-import {check, index, integer, text, timestamp, uuid} from 'drizzle-orm/pg-core';
+import {check, index, integer, pgEnum, text, timestamp, uuid} from 'drizzle-orm/pg-core';
 import type {Reservation} from '#core/entities/reservation.js';
 import {pgTable} from './common.js';
 
+export const reservationKindEnum = pgEnum('runners_reservation_kind', ['bound', 'launch']);
+
 export const reservations = pgTable(
   'reservations',
   {
@@ -12,6 +14,7 @@ export const reservations = pgTable(
     provisionerId: uuid('provisioner_id').notNull(),
     requiredLabels: text('required_labels').array().notNull(),
     count: integer('count').notNull(),
+    kind: reservationKindEnum('kind').notNull().default('launch'),
     createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
     expiresAt: timestamp('expires_at', {withTimezone: true}).notNull(),
   },
@@ -32,6 +35,7 @@ export function toReservation(row: ReservationDb): Reservation {
     provisionerId: row.provisionerId,
     requiredLabels: row.requiredLabels,
     count: row.count,
+    kind: row.kind,
     createdAt: row.createdAt,
     expiresAt: row.expiresAt,
   };

package/src/db/schema/runner-instances.ts

@@ -14,6 +14,12 @@ export const providerRunnerStateEnum = pgEnum('runners_provider_runner_state', [
   'terminated',
 ]);
 
+export const providerRunnerLaunchKindEnum = pgEnum('runners_provider_runner_launch_kind', [
+  'demand',
+  'warm',
+  'manual',
+]);
+
 export const providerRunners = pgTable(
   'runner_instances',
   {
@@ -25,6 +31,7 @@ export const providerRunners = pgTable(
     providerRunnerId: text('provider_runner_id'),
     intendedReservationId: uuid('intended_reservation_id'),
     reservationId: uuid('reservation_id'),
+    launchKind: providerRunnerLaunchKindEnum('launch_kind').notNull().default('manual'),
     assignedAt: timestamp('assigned_at', {withTimezone: true}),
     templateKey: text('template_key'),
     labels: text('labels').array().notNull().default([]),
@@ -82,7 +89,9 @@ export function toRunnerInstance(row: RunnerInstanceDb): RunnerInstance {
     workspaceId: row.workspaceId,
     provisionerId: row.provisionerId,
     providerRunnerId: row.providerRunnerId,
+    intendedReservationId: row.intendedReservationId,
     reservationId: row.reservationId,
+    launchKind: row.launchKind,
     assignedAt: row.assignedAt,
     templateKey: row.templateKey,
     labels: row.labels,

package/src/metrics/index.ts

@@ -1,13 +1,22 @@
-export type {RunnerReservationPromotionFailureReason} from './instance.js';
+export type {
+  RunnerActivationTokenNotIssuedReason,
+  RunnerActivationTokenNotIssuedSurface,
+  RunnerReservationCapacityFailureReason,
+  RunnerReservationPromotionFailureReason,
+} from './instance.js';
 export {
   jobExecutionClaimedCount,
   jobExecutionEnqueuedCount,
   jobExecutionLeaseExpiredCount,
   providerRunnerAbsentTerminatedCount,
+  providerRunnerActivationOutcomeCount,
   providerRunnerCountDivergenceCount,
   providerRunnerReconcileCallCount,
   providerRunnerTerminateIntentHonoredCount,
   providerRunnerTerminateIntentIssuedCount,
+  recordProviderRunnerActivationOutcome,
+  recordRunnerActivationTokenNotIssued,
+  recordRunnerReservationCapacityFailure,
   recordRunnerReservationPromotionFailure,
   recordRunnersRateLimitCheck,
   recordRunnersRateLimitPruneFailure,

package/src/metrics/instance.ts

@@ -31,6 +31,21 @@ export const runnerBootstrapExchangeCount = meter.createCounter<{
   description: 'Runner bootstrap-token exchanges by outcome',
 });
 
+export type RunnerActivationTokenNotIssuedReason =
+  | 'runner-not-found'
+  | 'missing-workspace'
+  | 'existing-session'
+  | 'not-running';
+
+export type RunnerActivationTokenNotIssuedSurface = 'enrollment' | 'poll';
+
+export const runnerActivationTokenNotIssuedCount = meter.createCounter<{
+  reason: RunnerActivationTokenNotIssuedReason;
+  surface: RunnerActivationTokenNotIssuedSurface;
+}>('runners_runner_activation_token_not_issued', {
+  description: 'Runner activation token issuance skips by reason and surface',
+});
+
 export const runnerControlHeartbeatCount = meter.createCounter<Record<string, never>>(
   'runners_runner_control_heartbeat',
   {description: 'Pre-workspace runner-control heartbeats accepted'},
@@ -67,17 +82,23 @@ export const providerRunnerAbsentTerminatedCount = meter.createCounter<Record<st
 
 export const providerRunnerTerminateIntentIssuedCount = meter.createCounter<{
   surface: 'poll-demand' | 'reconcile';
-  reason: 'job-cancelled' | 'terminal-state';
+  reason: 'activation-timeout' | 'job-cancelled' | 'terminal-state';
 }>('runners_provider_runner_terminate_intent_issued', {
   description: 'Provisioned runner terminate intents returned to provisioners',
 });
 
 export const providerRunnerTerminateIntentHonoredCount = meter.createCounter<{
-  reason: 'job-cancelled';
+  reason: 'activation-timeout' | 'job-cancelled';
 }>('runners_provider_runner_terminate_intent_honored', {
   description: 'Provisioned runner terminate intents honored by first transition to terminated',
 });
 
+export const providerRunnerActivationOutcomeCount = meter.createCounter<{
+  outcome: 'reaped' | 'rebound';
+}>('runners_provider_runner_activation_outcome', {
+  description: 'Demand-backed runner activation outcomes by recovery action',
+});
+
 export const reservationReleasedCount = meter.createCounter<Record<string, never>>(
   'runners_reservation_released',
   {description: 'Reservation units released from terminal provisioned runner reports'},
@@ -95,6 +116,18 @@ export const runnerReservationPromotionFailureCount = meter.createCounter<{
   description: 'Runner reservation promotion failures during enrollment by reason',
 });
 
+export type RunnerReservationCapacityFailureReason =
+  | 'reservation-not-found'
+  | 'reservation-kind-mismatch'
+  | 'reservation-expired'
+  | 'capacity-exhausted';
+
+export const runnerReservationCapacityFailureCount = meter.createCounter<{
+  reason: RunnerReservationCapacityFailureReason;
+}>('runners_reservation_capacity_failures', {
+  description: 'Runner reservation admission shortfalls by reason',
+});
+
 export type RunnersRateLimitAction = 'provisioner-mint' | 'ephemeral-register';
 export type RunnersRateLimitScope = 'provisioner' | 'ephemeral-token';
 export type RunnersRateLimitOutcome = 'allowed' | 'blocked' | 'unavailable';
@@ -125,6 +158,21 @@ export function recordRunnerReservationPromotionFailure(
   recordMetric(() => runnerReservationPromotionFailureCount.add(1, {reason}));
 }
 
+export function recordRunnerActivationTokenNotIssued(params: {
+  reason: RunnerActivationTokenNotIssuedReason;
+  surface: RunnerActivationTokenNotIssuedSurface;
+}): void {
+  recordMetric(() => runnerActivationTokenNotIssuedCount.add(1, params));
+}
+
+export function recordRunnerReservationCapacityFailure(
+  reason: RunnerReservationCapacityFailureReason,
+  count: number,
+): void {
+  if (count <= 0) return;
+  recordMetric(() => runnerReservationCapacityFailureCount.add(count, {reason}));
+}
+
 export function recordRunnersRateLimitCheck(params: {
   action: RunnersRateLimitAction;
   scope: RunnersRateLimitScope;
@@ -142,3 +190,12 @@ export function recordRunnersRateLimitCheck(params: {
 export function recordRunnersRateLimitPruneFailure(): void {
   recordMetric(() => rateLimitPruneFailureCount.add(1));
 }
+
+export function recordProviderRunnerActivationOutcome(params: {
+  outcome: 'reaped' | 'rebound';
+  count?: number;
+}): void {
+  recordMetric(() =>
+    providerRunnerActivationOutcomeCount.add(params.count ?? 1, {outcome: params.outcome}),
+  );
+}

package/src/metrics/service.test.ts

@@ -33,7 +33,14 @@ vi.mock('#db/runner-instances.js', () => ({
   countStaleEnrolledRunnerInstances: mocks.countStaleEnrolledRunnerInstances,
 }));
 
-import {registerRunnersServiceMetrics} from './service.js';
+let registerRunnersServiceMetrics: typeof import('./service.js').registerRunnersServiceMetrics;
+
+beforeAll(async () => {
+  // This package intentionally runs with isolate: false. Reset the shared module cache before
+  // importing the service so a previous file's real OpenTelemetry module cannot bypass this mock.
+  vi.resetModules();
+  ({registerRunnersServiceMetrics} = await import('./service.js'));
+});
 
 describe('registerRunnersServiceMetrics', () => {
   beforeEach(() => {

package/src/presentation/dto/poll-demand.ts

@@ -17,6 +17,9 @@ export function toPollDemandResponseDto(result: PollDemandResult): PollDemandRes
       count: reservation.count,
       expires_at: reservation.expiresAt.toISOString(),
     })),
+    ...(result.newlyReservedCount !== undefined
+      ? {newly_reserved_count: result.newlyReservedCount}
+      : {}),
     terminate_provider_runner_ids: result.terminateRunnerInstanceIds,
   };
 }

package/src/presentation/dto/runner-instances.ts

@@ -14,10 +14,14 @@ export function toReportRunnerInstancesResponseDto(result: ReportRunnerInstances
   };
 }
 
-export function toReconcileRunnerInstancesResponseDto(result: ReconcileRunnerInstancesResult): {
+export function toReconcileRunnerInstancesResponseDto(
+  result: ReconcileRunnerInstancesResult,
+  options: {includeIntendedReservationId: boolean},
+): {
   runners: Array<{
     provider_runner_id: string;
     state: ReconcileRunnerInstancesResult['runners'][number]['state'];
+    intended_reservation_id?: string | null;
     reservation_id: string | null;
     runner_session_id: string | null;
     bound_job: {
@@ -34,6 +38,9 @@ export function toReconcileRunnerInstancesResponseDto(result: ReconcileRunnerIns
     runners: result.runners.map((runner) => ({
       provider_runner_id: runner.providerRunnerId,
       state: runner.state,
+      ...(options.includeIntendedReservationId
+        ? {intended_reservation_id: runner.intendedReservationId}
+        : {}),
       reservation_id: runner.reservationId,
       runner_session_id: runner.runnerSessionId,
       bound_job: runner.boundJobExecution

package/src/presentation/routes/assign-runner-instances.ts

@@ -2,6 +2,8 @@ import {requireProvisionerContext} from '@shipfox/api-auth-context';
 import {
   assignRunnerInstancesBodySchema,
   assignRunnerInstancesResponseSchema,
+  RESERVATION_EXPIRED_ERROR_CODE,
+  RUNNER_INSTANCE_NOT_ASSIGNABLE_ERROR_CODE,
 } from '@shipfox/api-runners-dto';
 import {ClientError, defineRoute} from '@shipfox/node-fastify';
 import {
@@ -24,14 +26,16 @@ export const assignRunnerInstancesRoute = defineRoute({
     if (error instanceof ReservationNotFoundError)
       throw new ClientError('Reservation not found', 'reservation-not-found', {status: 404});
     if (error instanceof ReservationExpiredError)
-      throw new ClientError('Reservation has expired', 'reservation-expired', {status: 409});
+      throw new ClientError('Reservation has expired', RESERVATION_EXPIRED_ERROR_CODE, {
+        status: 409,
+      });
     if (
       error instanceof RunnerInstanceAlreadyAssignedError ||
       error instanceof RunnerInstanceNotAssignableError
     )
       throw new ClientError(
         'Runner instance cannot be assigned',
-        'runner-instance-not-assignable',
+        RUNNER_INSTANCE_NOT_ASSIGNABLE_ERROR_CODE,
         {status: 409},
       );
     throw error;