@shipfox/api-runners 12.1.0 → 12.3.0

package/drizzle/meta/_journal.json

@@ -29,6 +29,13 @@
       "when": 1785235910167,
       "tag": "0003_flaky_sally_floyd",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1786017247182,
+      "tag": "0004_huge_skreet",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-runners",
   "license": "MIT",
-  "version": "12.1.0",
+  "version": "12.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -22,24 +22,24 @@
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
     "@shipfox/api-common-dto": "12.0.0",
-    "@shipfox/api-auth-context": "12.0.0",
+    "@shipfox/api-auth-context": "12.2.0",
     "@shipfox/api-auth-dto": "12.0.0",
-    "@shipfox/api-runners-dto": "12.0.0",
-    "@shipfox/api-workflows-dto": "12.1.0",
+    "@shipfox/api-runners-dto": "12.2.0",
+    "@shipfox/api-workflows-dto": "12.3.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
     "@shipfox/node-drizzle": "0.3.5",
     "@shipfox/node-error-monitoring": "0.3.0",
     "@shipfox/node-auth-root-key": "0.2.3",
-    "@shipfox/node-fastify": "0.4.1",
-    "@shipfox/node-module": "1.0.5",
-    "@shipfox/node-opentelemetry": "0.6.3",
+    "@shipfox/node-fastify": "0.4.2",
+    "@shipfox/node-module": "1.0.6",
+    "@shipfox/node-opentelemetry": "0.6.4",
     "@shipfox/node-outbox": "0.2.6",
     "@shipfox/node-postgres": "0.5.0",
     "@shipfox/node-rate-limit": "0.4.0",
-    "@shipfox/node-temporal": "0.4.4",
+    "@shipfox/node-temporal": "0.4.5",
     "@shipfox/node-tokens": "0.3.2",
-    "@shipfox/runner-labels": "0.1.3"
+    "@shipfox/runner-labels": "0.2.0"
   },
   "imports": {
     "#*": "./dist/*"

package/src/config.test.ts

@@ -1,6 +1,42 @@
 import {RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS} from '@shipfox/api-runners-dto';
 import {vi} from '@shipfox/vitest/vi';
 
+describe('RUNNER_RESERVED_LABELS', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it('defaults to no reserved labels', async () => {
+    vi.stubEnv('RUNNER_RESERVED_LABELS', undefined);
+    vi.resetModules();
+
+    const {config, runnerReservedLabels} = await import('#config.js');
+
+    expect(config.RUNNER_RESERVED_LABELS).toBe('');
+    expect(runnerReservedLabels).toEqual([]);
+  });
+
+  it('parses comma-separated labels for case-insensitive matching', async () => {
+    vi.stubEnv('RUNNER_RESERVED_LABELS', ' ShipFox-Managed, Linux,shipfox-managed ');
+    vi.resetModules();
+
+    const {config, runnerReservedLabels} = await import('#config.js');
+
+    expect(config.RUNNER_RESERVED_LABELS).toBe(' ShipFox-Managed, Linux,shipfox-managed ');
+    expect(runnerReservedLabels).toEqual(['linux', 'shipfox-managed']);
+  });
+
+  it('rejects invalid runner labels', async () => {
+    vi.stubEnv('RUNNER_RESERVED_LABELS', 'linux,has space');
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow(
+      'RUNNER_RESERVED_LABELS contains invalid runner label(s): has space',
+    );
+  });
+});
+
 describe('EPHEMERAL_REGISTRATION_TOKEN_TTL_SECONDS validation', () => {
   afterEach(() => {
     vi.unstubAllEnvs();
@@ -49,6 +85,51 @@ describe('runner assignment polling defaults', () => {
     await expect(import('#config.js')).rejects.toThrow('RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS');
   });
 });
+
+describe('reservation TTL ceiling validation', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it.each([
+    '0',
+    '-5',
+    '1.5',
+    '3601',
+  ])('fails startup when RESERVATION_TTL_MAX_SECONDS is %s', async (value) => {
+    vi.stubEnv('RESERVATION_TTL_MAX_SECONDS', value);
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow('RESERVATION_TTL_MAX_SECONDS');
+  });
+
+  it('defaults high enough for provider registration deadlines and launch headroom', async () => {
+    vi.resetModules();
+
+    const {config} = await import('#config.js');
+
+    expect(config.RESERVATION_TTL_MAX_SECONDS).toBe(600);
+  });
+
+  it('accepts a whole-second ceiling inside the hard maximum', async () => {
+    vi.stubEnv('RESERVATION_TTL_MAX_SECONDS', '600');
+    vi.resetModules();
+
+    const {config} = await import('#config.js');
+
+    expect(config.RESERVATION_TTL_MAX_SECONDS).toBe(600);
+  });
+
+  it('fails startup when the default reservation TTL is above the ceiling', async () => {
+    vi.stubEnv('RESERVATION_TTL_SECONDS', '600');
+    vi.stubEnv('RESERVATION_TTL_MAX_SECONDS', '300');
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow('RESERVATION_TTL_SECONDS');
+  });
+});
+
 describe('REGISTRATION_TOKEN_BATCH_MAX validation', () => {
   afterEach(() => {
     vi.unstubAllEnvs();

package/src/config.ts

@@ -1,10 +1,12 @@
 import {RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS} from '@shipfox/api-runners-dto';
-import {bool, createConfig, num} from '@shipfox/config';
+import {bool, createConfig, num, str} from '@shipfox/config';
+import {findInvalidLabels, parseLabelList} from '@shipfox/runner-labels';
 import {STUCK_JOB_THRESHOLD_SECONDS} from '#core/maintenance-policy.js';
 
 const EPHEMERAL_REGISTRATION_TOKEN_TTL_HARD_MAX_SECONDS = 3600;
 const REGISTRATION_TOKEN_BATCH_HARD_MAX = 1000;
 const RUNNER_CONTROL_PLANE_TOKEN_TTL_HARD_MAX_SECONDS = 3600;
+const RESERVATION_TTL_HARD_MAX_SECONDS = 3600;
 
 export const config = createConfig({
   RUNNER_BOOTSTRAP_TOKEN_TTL_SECONDS: num({
@@ -27,6 +29,10 @@ export const config = createConfig({
     desc: 'Delay between durable assignment reads while a runner-control session waits for an assignment, in milliseconds.',
     default: 250,
   }),
+  RUNNER_RESERVED_LABELS: str({
+    desc: 'Comma-separated labels that only installation-scope provisioners may advertise. Any other provisioner or runner has them removed.',
+    default: '',
+  }),
   EPHEMERAL_REGISTRATION_TOKEN_TTL_SECONDS: num({
     desc: `Lifetime of a provisioner-minted runner registration token, in seconds. The token can be exchanged once by a runner before this time passes. Set this between 1 and ${EPHEMERAL_REGISTRATION_TOKEN_TTL_HARD_MAX_SECONDS}.`,
     default: 300,
@@ -56,9 +62,13 @@ export const config = createConfig({
     default: 250,
   }),
   RESERVATION_TTL_SECONDS: num({
-    desc: 'Lifetime of a count-based runner reservation, in seconds. Expired reservations stop counting against queued demand.',
+    desc: 'Default lifetime and activation grace period of a count-based runner reservation, in seconds. A runner without a session can be rebound only after this deadline. Used when a provisioner does not request a provider-specific value. Expired reservations stop counting against queued demand.',
     default: 60,
   }),
+  RESERVATION_TTL_MAX_SECONDS: num({
+    desc: `Server-side ceiling for a count-based runner reservation lifetime and activation grace period, in seconds. Set it at least as high as every provider registration deadline plus its launch headroom so provider-specific values can cover the launch gap, boot, and enrollment. Set this between 1 and ${RESERVATION_TTL_HARD_MAX_SECONDS}.`,
+    default: 600,
+  }),
   RESERVATION_LONG_POLL_MAX_WAIT_SECONDS: num({
     desc: 'Maximum time the provisioner demand poll endpoint waits for reservable demand before returning, in seconds.',
     default: 30,
@@ -133,6 +143,17 @@ export const config = createConfig({
   }),
 });
 
+const parsedRunnerReservedLabels = parseLabelList(config.RUNNER_RESERVED_LABELS);
+const invalidRunnerReservedLabels = findInvalidLabels(parsedRunnerReservedLabels);
+
+if (invalidRunnerReservedLabels.length > 0) {
+  throw new Error(
+    `RUNNER_RESERVED_LABELS contains invalid runner label(s): ${invalidRunnerReservedLabels.join(', ')}`,
+  );
+}
+
+export const runnerReservedLabels = parsedRunnerReservedLabels;
+
 if (
   !Number.isInteger(config.EPHEMERAL_REGISTRATION_TOKEN_TTL_SECONDS) ||
   config.EPHEMERAL_REGISTRATION_TOKEN_TTL_SECONDS < 1 ||
@@ -209,6 +230,22 @@ if (!Number.isInteger(config.RESERVATION_TTL_SECONDS) || config.RESERVATION_TTL_
   );
 }
 
+if (
+  !Number.isInteger(config.RESERVATION_TTL_MAX_SECONDS) ||
+  config.RESERVATION_TTL_MAX_SECONDS < 1 ||
+  config.RESERVATION_TTL_MAX_SECONDS > RESERVATION_TTL_HARD_MAX_SECONDS
+) {
+  throw new Error(
+    `RESERVATION_TTL_MAX_SECONDS (${config.RESERVATION_TTL_MAX_SECONDS}) must be a whole number of seconds between 1 and ${RESERVATION_TTL_HARD_MAX_SECONDS}.`,
+  );
+}
+
+if (config.RESERVATION_TTL_SECONDS > config.RESERVATION_TTL_MAX_SECONDS) {
+  throw new Error(
+    `RESERVATION_TTL_SECONDS (${config.RESERVATION_TTL_SECONDS}) must not be greater than RESERVATION_TTL_MAX_SECONDS (${config.RESERVATION_TTL_MAX_SECONDS}).`,
+  );
+}
+
 if (
   !Number.isInteger(config.RESERVATION_LONG_POLL_MAX_WAIT_SECONDS) ||
   config.RESERVATION_LONG_POLL_MAX_WAIT_SECONDS < 0

package/src/core/errors.ts

@@ -40,6 +40,15 @@ export class EmptyRunnerLabelsError extends Error {
   }
 }
 
+export class RunnerLabelsReservedError extends Error {
+  constructor(public readonly labels: string[]) {
+    super(
+      `All supplied runner labels are reserved for installation-scope provisioners: ${labels.join(', ')}`,
+    );
+    this.name = 'RunnerLabelsReservedError';
+  }
+}
+
 export class EmptyRequiredLabelsError extends Error {
   constructor() {
     super('Required labels cannot be empty');

package/src/core/index.ts

@@ -25,6 +25,7 @@ export {
   ProvisionerTokenNotFoundError,
   RegistrationTokenConsumedError,
   RegistrationTokenExpiredError,
+  RunnerLabelsReservedError,
   RunnerSessionExhaustedError,
   RunningJobExecutionNotFoundError,
 } from './errors.js';

package/src/core/runner-control-sessions.test.ts

@@ -0,0 +1,404 @@
+import type {RunnerToolCapabilitiesDto} from '@shipfox/api-runners-dto';
+import {afterEach, vi} from '@shipfox/vitest/vi';
+import {eq, inArray} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {provisionerTokens} from '#db/schema/provisioner-tokens.js';
+import {reservations} from '#db/schema/reservations.js';
+import {runnerActivationTokens} from '#db/schema/runner-activation-tokens.js';
+import {runnerControlSessions} from '#db/schema/runner-control-sessions.js';
+import {providerRunners} from '#db/schema/runner-instances.js';
+import {
+  type RunnerReservationPromotionFailureReason,
+  runnerReservationPromotionFailureCount,
+} from '#metrics/instance.js';
+import {enrollRunnerControlSession} from './runner-control-sessions.js';
+
+const createdReservationIds = new Set<string>();
+const createdProvisionerTokenIds = new Set<string>();
+const createdRunnerInstanceIds = new Set<string>();
+
+afterEach(async () => {
+  const runnerInstanceIds = [...createdRunnerInstanceIds];
+  const reservationIds = [...createdReservationIds];
+
+  if (runnerInstanceIds.length > 0) {
+    await db()
+      .delete(runnerActivationTokens)
+      .where(inArray(runnerActivationTokens.runnerInstanceId, runnerInstanceIds));
+    await db()
+      .delete(runnerControlSessions)
+      .where(inArray(runnerControlSessions.runnerInstanceId, runnerInstanceIds));
+    await db().delete(providerRunners).where(inArray(providerRunners.id, runnerInstanceIds));
+  }
+  if (reservationIds.length > 0)
+    await db().delete(reservations).where(inArray(reservations.id, reservationIds));
+  if (createdProvisionerTokenIds.size > 0)
+    await db()
+      .delete(provisionerTokens)
+      .where(inArray(provisionerTokens.id, [...createdProvisionerTokenIds]));
+
+  createdRunnerInstanceIds.clear();
+  createdReservationIds.clear();
+  createdProvisionerTokenIds.clear();
+});
+
+describe('enrollRunnerControlSession', () => {
+  it('counts expired reservation promotion failures', async () => {
+    const provisionerId = crypto.randomUUID();
+    const reservation = await createReservation({
+      provisionerId,
+      expiresAt: new Date(Date.now() - 1_000),
+    });
+
+    await expectPromotionFailure({
+      provisionerId,
+      intendedReservationId: reservation.id,
+      reason: 'reservation-expired',
+    });
+  });
+
+  it('counts missing reservation promotion failures', async () => {
+    await expectPromotionFailure({
+      provisionerId: crypto.randomUUID(),
+      intendedReservationId: crypto.randomUUID(),
+      reason: 'reservation-not-found',
+    });
+  });
+
+  it('counts already-assigned reservation promotion failures', async () => {
+    const provisionerId = crypto.randomUUID();
+    const intendedReservation = await createReservation({provisionerId});
+    const assignedReservation = await createReservation({provisionerId});
+
+    await expectPromotionFailure({
+      provisionerId,
+      intendedReservationId: intendedReservation.id,
+      reservationId: assignedReservation.id,
+      reason: 'already-assigned',
+    });
+  });
+
+  it('counts not-assignable reservation promotion failures', async () => {
+    const provisionerId = crypto.randomUUID();
+    const reservation = await createReservation({
+      provisionerId,
+      requiredLabels: ['gpu'],
+    });
+
+    await expectPromotionFailure({
+      provisionerId,
+      intendedReservationId: reservation.id,
+      labels: ['linux'],
+      reason: 'not-assignable',
+    });
+  });
+
+  it('does not count successful reservation promotion', async () => {
+    const provisionerId = crypto.randomUUID();
+    const reservation = await createReservation({provisionerId});
+    const runnerInstanceId = await createRunner({
+      provisionerId,
+      intendedReservationId: reservation.id,
+    });
+    const addSpy = vi.spyOn(runnerReservationPromotionFailureCount, 'add');
+
+    try {
+      const activationToken = await enrollRunnerControlSession({
+        runnerInstanceId,
+        provisionerId,
+        labels: ['linux'],
+        providerKind: 'docker',
+        protocolVersion: '1',
+      });
+
+      expect(activationToken).toEqual(expect.any(String));
+      expect(addSpy).not.toHaveBeenCalled();
+    } finally {
+      addSpy.mockRestore();
+    }
+  });
+
+  it('preserves committed assignment metadata during a later enrollment', async () => {
+    const provisionerId = crypto.randomUUID();
+    const reservation = await createReservation({provisionerId});
+    const committedCapabilities: RunnerToolCapabilitiesDto = {
+      harnesses: {pi: {tools: ['read']}},
+    };
+    const runnerInstanceId = await createRunner({
+      provisionerId,
+      intendedReservationId: reservation.id,
+      reservationId: reservation.id,
+      workspaceId: reservation.workspaceId,
+      assignedAt: new Date(),
+      labels: ['linux'],
+      providerKind: 'ec2',
+      protocolVersion: '1',
+      capabilities: committedCapabilities,
+    });
+
+    const activationToken = await enrollRunnerControlSession({
+      runnerInstanceId,
+      provisionerId,
+      labels: ['gpu'],
+      capabilities: {harnesses: {claude: {tools: ['bash']}}},
+      providerKind: 'docker',
+      protocolVersion: '2',
+    });
+    const [runner] = await db()
+      .select({
+        reservationId: providerRunners.reservationId,
+        labels: providerRunners.labels,
+        providerKind: providerRunners.providerKind,
+        protocolVersion: providerRunners.protocolVersion,
+        capabilities: providerRunners.capabilities,
+        state: providerRunners.state,
+      })
+      .from(providerRunners)
+      .where(eq(providerRunners.id, runnerInstanceId));
+
+    expect(activationToken).toEqual(expect.any(String));
+    expect(runner).toEqual({
+      reservationId: reservation.id,
+      labels: ['linux'],
+      providerKind: 'ec2',
+      protocolVersion: '1',
+      capabilities: committedCapabilities,
+      state: 'running',
+    });
+  });
+
+  it('updates metadata when a provider report precedes assignment commit', async () => {
+    const provisionerId = crypto.randomUUID();
+    const reservation = await createReservation({provisionerId});
+    const capabilities: RunnerToolCapabilitiesDto = {
+      harnesses: {pi: {tools: ['read']}},
+    };
+    const runnerInstanceId = await createRunner({
+      provisionerId,
+      intendedReservationId: reservation.id,
+      reservationId: reservation.id,
+      assignedAt: null,
+    });
+
+    const activationToken = await enrollRunnerControlSession({
+      runnerInstanceId,
+      provisionerId,
+      labels: ['linux'],
+      capabilities,
+      providerKind: 'ec2',
+      protocolVersion: '1',
+    });
+    const [runner] = await db()
+      .select({
+        reservationId: providerRunners.reservationId,
+        assignedAt: providerRunners.assignedAt,
+        labels: providerRunners.labels,
+        providerKind: providerRunners.providerKind,
+        protocolVersion: providerRunners.protocolVersion,
+        capabilities: providerRunners.capabilities,
+        state: providerRunners.state,
+      })
+      .from(providerRunners)
+      .where(eq(providerRunners.id, runnerInstanceId));
+
+    expect(activationToken).toBeNull();
+    expect(runner).toEqual({
+      reservationId: reservation.id,
+      assignedAt: null,
+      labels: ['linux'],
+      providerKind: 'ec2',
+      protocolVersion: '1',
+      capabilities,
+      state: 'running',
+    });
+  });
+
+  it('updates metadata during enrollment for an unassigned runner', async () => {
+    const provisionerId = crypto.randomUUID();
+    const capabilities: RunnerToolCapabilitiesDto = {
+      harnesses: {pi: {tools: ['read']}},
+    };
+    const runnerInstanceId = await createRunner({provisionerId});
+
+    const activationToken = await enrollRunnerControlSession({
+      runnerInstanceId,
+      provisionerId,
+      labels: ['linux'],
+      capabilities,
+      providerKind: 'docker',
+      protocolVersion: '1',
+    });
+    const [runner] = await db()
+      .select({
+        reservationId: providerRunners.reservationId,
+        labels: providerRunners.labels,
+        providerKind: providerRunners.providerKind,
+        protocolVersion: providerRunners.protocolVersion,
+        capabilities: providerRunners.capabilities,
+        state: providerRunners.state,
+      })
+      .from(providerRunners)
+      .where(eq(providerRunners.id, runnerInstanceId));
+
+    expect(activationToken).toBeNull();
+    expect(runner).toEqual({
+      reservationId: null,
+      labels: ['linux'],
+      providerKind: 'docker',
+      protocolVersion: '1',
+      capabilities,
+      state: 'running',
+    });
+  });
+
+  it('keeps unexpected promotion failures on the error-log path', async () => {
+    const provisionerId = crypto.randomUUID();
+    const reservation = await createReservation({provisionerId});
+    const runnerInstanceId = await createRunner({
+      provisionerId,
+      intendedReservationId: reservation.id,
+    });
+    const unexpectedError = new Error('database unavailable');
+    const debugLog = vi.fn();
+    const errorLog = vi.fn();
+
+    vi.resetModules();
+    vi.doMock('@shipfox/node-opentelemetry', async (importOriginal) => ({
+      ...(await importOriginal<typeof import('@shipfox/node-opentelemetry')>()),
+      logger: () => ({debug: debugLog, error: errorLog}),
+    }));
+    vi.doMock('#db/runner-assignments.js', async (importOriginal) => ({
+      ...(await importOriginal<typeof import('#db/runner-assignments.js')>()),
+      assignRunnerInstancesTx: vi.fn().mockRejectedValue(unexpectedError),
+    }));
+
+    const {closePostgresClient, createPostgresClient} = await import('@shipfox/node-postgres');
+    createPostgresClient();
+
+    try {
+      const {enrollRunnerControlSession: enroll} = await import('./runner-control-sessions.js');
+      const result = await enroll({
+        runnerInstanceId,
+        provisionerId,
+        labels: ['linux'],
+        providerKind: 'docker',
+        protocolVersion: '1',
+      });
+
+      expect(result).toBeNull();
+      expect(debugLog).not.toHaveBeenCalled();
+      expect(errorLog).toHaveBeenCalledWith(
+        expect.objectContaining({err: unexpectedError}),
+        'Unexpected failure promoting runner reservation during enrollment',
+      );
+    } finally {
+      await closePostgresClient();
+      vi.doUnmock('@shipfox/node-opentelemetry');
+      vi.doUnmock('#db/runner-assignments.js');
+      vi.resetModules();
+    }
+  });
+});
+
+async function expectPromotionFailure(params: {
+  provisionerId: string;
+  intendedReservationId: string;
+  reservationId?: string;
+  labels?: string[];
+  reason: RunnerReservationPromotionFailureReason;
+}): Promise<void> {
+  const runnerInstanceId = await createRunner(params);
+  const addSpy = vi.spyOn(runnerReservationPromotionFailureCount, 'add');
+
+  try {
+    const result = await enrollRunnerControlSession({
+      runnerInstanceId,
+      provisionerId: params.provisionerId,
+      labels: params.labels ?? ['linux'],
+      providerKind: 'docker',
+      protocolVersion: '1',
+    });
+
+    expect(result).toBeNull();
+    expect(addSpy).toHaveBeenCalledWith(1, {reason: params.reason});
+  } finally {
+    addSpy.mockRestore();
+  }
+}
+
+async function createReservation(params: {
+  provisionerId: string;
+  requiredLabels?: string[];
+  expiresAt?: Date;
+}) {
+  const [reservation] = await db()
+    .insert(reservations)
+    .values({
+      workspaceId: crypto.randomUUID(),
+      provisionerId: params.provisionerId,
+      requiredLabels: params.requiredLabels ?? ['linux'],
+      count: 1,
+      expiresAt: params.expiresAt ?? new Date(Date.now() + 60_000),
+    })
+    .returning();
+  if (!reservation) throw new Error('Expected reservation');
+  createdReservationIds.add(reservation.id);
+  return reservation;
+}
+
+async function createRunner(params: {
+  provisionerId: string;
+  intendedReservationId?: string | null;
+  reservationId?: string | null;
+  workspaceId?: string | null;
+  labels?: string[];
+  providerKind?: string | null;
+  protocolVersion?: string | null;
+  capabilities?: RunnerToolCapabilitiesDto | null;
+  assignedAt?: Date | null;
+}): Promise<string> {
+  const defaultAssignedAt = params.reservationId ? new Date() : null;
+
+  if (!createdProvisionerTokenIds.has(params.provisionerId)) {
+    await db().insert(provisionerTokens).values({
+      id: params.provisionerId,
+      scope: 'installation',
+      workspaceId: null,
+      hashedToken: crypto.randomUUID(),
+      prefix: 'test',
+      createdByUserId: crypto.randomUUID(),
+    });
+    createdProvisionerTokenIds.add(params.provisionerId);
+  }
+
+  const [runner] = await db()
+    .insert(providerRunners)
+    .values({
+      provisionerId: params.provisionerId,
+      intendedReservationId: params.intendedReservationId ?? null,
+      reservationId: params.reservationId ?? null,
+      workspaceId: params.workspaceId ?? null,
+      providerRunnerId: crypto.randomUUID(),
+      labels: params.labels ?? [],
+      providerKind: params.providerKind ?? null,
+      protocolVersion: params.protocolVersion ?? null,
+      capabilities: params.capabilities ?? null,
+      assignedAt: params.assignedAt === undefined ? defaultAssignedAt : params.assignedAt,
+      state: 'starting',
+      reportedAt: new Date(),
+    })
+    .returning({id: providerRunners.id});
+  if (!runner) throw new Error('Expected runner instance');
+  createdRunnerInstanceIds.add(runner.id);
+
+  await db()
+    .insert(runnerControlSessions)
+    .values({
+      runnerInstanceId: runner.id,
+      provisionerId: params.provisionerId,
+      hashedToken: crypto.randomUUID(),
+      prefix: 'test',
+      expiresAt: new Date(Date.now() + 60_000),
+    });
+  return runner.id;
+}