@shipfox/api-runners 12.3.0 → 12.4.1

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

@@ -9,6 +9,7 @@ import {runnerControlSessions} from '#db/schema/runner-control-sessions.js';
 import {providerRunners} from '#db/schema/runner-instances.js';
 import {
   type RunnerReservationPromotionFailureReason,
+  runnerActivationTokenNotIssuedCount,
   runnerReservationPromotionFailureCount,
 } from '#metrics/instance.js';
 import {enrollRunnerControlSession} from './runner-control-sessions.js';
@@ -167,7 +168,7 @@ describe('enrollRunnerControlSession', () => {
     });
   });
 
-  it('updates metadata when a provider report precedes assignment commit', async () => {
+  it('repairs assignment metadata when a provider report precedes assignment commit', async () => {
     const provisionerId = crypto.randomUUID();
     const reservation = await createReservation({provisionerId});
     const capabilities: RunnerToolCapabilitiesDto = {
@@ -190,8 +191,10 @@ describe('enrollRunnerControlSession', () => {
     });
     const [runner] = await db()
       .select({
+        workspaceId: providerRunners.workspaceId,
         reservationId: providerRunners.reservationId,
         assignedAt: providerRunners.assignedAt,
+        intendedReservationId: providerRunners.intendedReservationId,
         labels: providerRunners.labels,
         providerKind: providerRunners.providerKind,
         protocolVersion: providerRunners.protocolVersion,
@@ -201,10 +204,12 @@ describe('enrollRunnerControlSession', () => {
       .from(providerRunners)
       .where(eq(providerRunners.id, runnerInstanceId));
 
-    expect(activationToken).toBeNull();
+    expect(activationToken).toEqual(expect.any(String));
     expect(runner).toEqual({
+      workspaceId: reservation.workspaceId,
       reservationId: reservation.id,
-      assignedAt: null,
+      assignedAt: expect.any(Date),
+      intendedReservationId: null,
       labels: ['linux'],
       providerKind: 'ec2',
       protocolVersion: '1',
@@ -213,6 +218,62 @@ describe('enrollRunnerControlSession', () => {
     });
   });
 
+  it('records an activation-token reason when enrollment sees an existing runner session', async () => {
+    const provisionerId = crypto.randomUUID();
+    const reservation = await createReservation({provisionerId});
+    const runnerInstanceId = await createRunner({
+      provisionerId,
+      intendedReservationId: reservation.id,
+    });
+    await db()
+      .update(providerRunners)
+      .set({runnerSessionId: crypto.randomUUID()})
+      .where(eq(providerRunners.id, runnerInstanceId));
+    const addSpy = vi.spyOn(runnerActivationTokenNotIssuedCount, 'add');
+
+    try {
+      const activationToken = await enrollRunnerControlSession({
+        runnerInstanceId,
+        provisionerId,
+        labels: ['linux'],
+        providerKind: 'docker',
+        protocolVersion: '1',
+      });
+      const [runner] = await db()
+        .select({
+          workspaceId: providerRunners.workspaceId,
+          reservationId: providerRunners.reservationId,
+          assignedAt: providerRunners.assignedAt,
+          intendedReservationId: providerRunners.intendedReservationId,
+          runnerSessionId: providerRunners.runnerSessionId,
+          state: providerRunners.state,
+        })
+        .from(providerRunners)
+        .where(eq(providerRunners.id, runnerInstanceId));
+
+      expect(activationToken).toBeNull();
+      expect(runner).toEqual({
+        workspaceId: reservation.workspaceId,
+        reservationId: reservation.id,
+        assignedAt: expect.any(Date),
+        intendedReservationId: null,
+        runnerSessionId: expect.any(String),
+        state: 'running',
+      });
+      // The test setup uses a shared NoopMeter counter; count only this metric's label shape.
+      const activationTokenCalls = addSpy.mock.calls.filter(
+        ([value, attributes]) =>
+          value === 1 &&
+          (attributes as {reason?: string; surface?: string} | undefined)?.reason ===
+            'existing-session' &&
+          (attributes as {reason?: string; surface?: string} | undefined)?.surface === 'enrollment',
+      );
+      expect(activationTokenCalls).toHaveLength(1);
+    } finally {
+      addSpy.mockRestore();
+    }
+  });
+
   it('updates metadata during enrollment for an unassigned runner', async () => {
     const provisionerId = crypto.randomUUID();
     const capabilities: RunnerToolCapabilitiesDto = {
@@ -298,6 +359,77 @@ describe('enrollRunnerControlSession', () => {
       vi.resetModules();
     }
   });
+
+  it('records a rolled-back assignment rejection without recording its assignment timing', async () => {
+    const provisionerId = crypto.randomUUID();
+    const reservation = await createReservation({provisionerId});
+    const runnerInstanceId = await createRunner({
+      provisionerId,
+      intendedReservationId: reservation.id,
+    });
+    const assignmentTimingRecord = vi.fn();
+    const assignmentRejectionRecord = vi.fn();
+    const promotionFailureRecord = vi.fn();
+
+    vi.resetModules();
+    const {RunnerInstanceNotAssignableError} = await import('#core/errors.js');
+    const activationIssueError = new RunnerInstanceNotAssignableError(
+      runnerInstanceId,
+      'capacity-exhausted',
+    );
+    vi.doMock('#metrics/index.js', async (importOriginal) => ({
+      ...(await importOriginal<typeof import('#metrics/index.js')>()),
+      recordProviderRunnerControlSessionToAssignment: assignmentTimingRecord,
+      recordProviderRunnerAssignmentRejected: assignmentRejectionRecord,
+      recordRunnerReservationPromotionFailure: promotionFailureRecord,
+    }));
+    vi.doMock('./runner-activation.js', async (importOriginal) => ({
+      ...(await importOriginal<typeof import('./runner-activation.js')>()),
+      issueRunnerActivationTokenTx: vi.fn().mockRejectedValue(activationIssueError),
+    }));
+
+    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',
+      });
+      const [runner] = await db()
+        .select({
+          intendedReservationId: providerRunners.intendedReservationId,
+          reservationId: providerRunners.reservationId,
+          workspaceId: providerRunners.workspaceId,
+          assignedAt: providerRunners.assignedAt,
+        })
+        .from(providerRunners)
+        .where(eq(providerRunners.id, runnerInstanceId));
+
+      expect(result).toBeNull();
+      expect(runner).toEqual({
+        intendedReservationId: reservation.id,
+        reservationId: null,
+        workspaceId: null,
+        assignedAt: null,
+      });
+      expect(assignmentTimingRecord).not.toHaveBeenCalled();
+      expect(assignmentRejectionRecord).toHaveBeenCalledWith({
+        reason: 'capacity-exhausted',
+        surface: 'enrollment',
+      });
+      expect(promotionFailureRecord).toHaveBeenCalledWith('not-assignable');
+    } finally {
+      await closePostgresClient();
+      vi.doUnmock('#metrics/index.js');
+      vi.doUnmock('./runner-activation.js');
+      vi.resetModules();
+    }
+  });
 });
 
 async function expectPromotionFailure(params: {

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

@@ -5,6 +5,7 @@ import {extractDisplayPrefix, generateOpaqueToken, hashOpaqueToken} from '@shipf
 import {and, eq, gt, isNull, notInArray, or, sql} from 'drizzle-orm';
 import {config} from '#config.js';
 import {
+  getRunnerAssignmentRejectionReason,
   ReservationExpiredError,
   ReservationNotFoundError,
   RunnerInstanceAlreadyAssignedError,
@@ -12,13 +13,20 @@ import {
 } from '#core/errors.js';
 import {sanitizeRunnerLabels} from '#core/runner-labels.js';
 import {db, type schema, type Tx} from '#db/db.js';
-import {assignRunnerInstancesTx} from '#db/runner-assignments.js';
-import {terminalStates} from '#db/runner-instances.js';
+import {
+  assignRunnerInstancesTx,
+  validateRunnerReservationCapacityTx,
+} from '#db/runner-assignments.js';
+import {terminalStates} from '#db/runner-states.js';
 import {provisionerTokens} from '#db/schema/provisioner-tokens.js';
 import {runnerBootstrapTokens, runnerControlSessions} from '#db/schema/runner-control-sessions.js';
 import {providerRunners} from '#db/schema/runner-instances.js';
 import {
   type RunnerReservationPromotionFailureReason,
+  recordProviderRunnerAssignmentRejected,
+  recordProviderRunnerControlSessionToAssignment,
+  recordProviderRunnerCreatedToControlSession,
+  recordRunnerReservationCapacityFailure,
   recordRunnerReservationPromotionFailure,
 } from '#metrics/index.js';
 import {issueRunnerActivationTokenTx} from './runner-activation.js';
@@ -45,27 +53,72 @@ export async function createRunnerInstancesWithBootstrapTokens(params: {
     reservationId?: string | null;
   }>;
   ttlSeconds: number;
-}): Promise<Array<{runnerInstanceId: string; bootstrapToken: string}>> {
+}): Promise<{
+  runnerInstances: Array<{
+    runnerInstanceId: string;
+    bootstrapToken: string;
+    requestIndex: number;
+  }>;
+  reservationUnavailable: boolean;
+}> {
   const expiresAt = new Date(Date.now() + params.ttlSeconds * 1000);
   return await db().transaction(async (tx) => {
+    const reservationValidation = await validateRunnerReservationCapacityTx(tx, {
+      provisionerId: params.provisionerId,
+      requests: params.runnerInstances.reduce(
+        (requests, runner) => {
+          if (!runner.reservationId) return requests;
+          const request = requests.find(
+            (candidate) => candidate.reservationId === runner.reservationId,
+          );
+          if (request) request.count += 1;
+          else requests.push({reservationId: runner.reservationId, count: 1});
+          return requests;
+        },
+        [] as Array<{reservationId: string; count: number}>,
+      ),
+    });
+    for (const {reason, count} of reservationValidation.unavailableByReservation.values())
+      recordRunnerReservationCapacityFailure(reason, count);
+    const remainingAcceptedByReservation = new Map(reservationValidation.acceptedByReservation);
+    const runnerInstances = params.runnerInstances.flatMap((runner, requestIndex) => {
+      if (!runner.reservationId) return [{...runner, requestIndex}];
+      const remaining = remainingAcceptedByReservation.get(runner.reservationId) ?? 0;
+      if (remaining === 0) return [];
+      remainingAcceptedByReservation.set(runner.reservationId, remaining - 1);
+      return [{...runner, requestIndex}];
+    });
+
+    if (runnerInstances.length === 0)
+      return {
+        runnerInstances: [],
+        reservationUnavailable: reservationValidation.unavailableByReservation.size > 0,
+      };
+
     const instances = await tx
       .insert(providerRunners)
       .values(
-        params.runnerInstances.map((runner) => ({
+        runnerInstances.map((runner) => ({
           provisionerId: params.provisionerId,
           providerKind: params.providerKind ?? null,
           templateKey: runner.templateKey ?? null,
           intendedReservationId: runner.reservationId ?? null,
+          launchKind: runner.reservationId ? ('demand' as const) : ('warm' as const),
           state: 'starting' as const,
           labels: [],
           reportedAt: new Date(),
         })),
       )
       .returning({id: providerRunners.id});
-    const results = instances.map((instance) => ({
-      runnerInstanceId: instance.id,
-      bootstrapToken: generateOpaqueToken('runnerBootstrapToken'),
-    }));
+    const results = instances.map((instance, index) => {
+      const runner = runnerInstances[index];
+      if (!runner) throw new Error('Runner instance insert returned an unexpected row count');
+      return {
+        runnerInstanceId: instance.id,
+        bootstrapToken: generateOpaqueToken('runnerBootstrapToken'),
+        requestIndex: runner.requestIndex,
+      };
+    });
     await tx.insert(runnerBootstrapTokens).values(
       results.map((result) => ({
         runnerInstanceId: result.runnerInstanceId,
@@ -75,7 +128,10 @@ export async function createRunnerInstancesWithBootstrapTokens(params: {
         expiresAt,
       })),
     );
-    return results;
+    return {
+      runnerInstances: results,
+      reservationUnavailable: reservationValidation.unavailableByReservation.size > 0,
+    };
   });
 }
 
@@ -85,7 +141,7 @@ export async function exchangeRunnerBootstrapToken(params: {
 }): Promise<{runnerInstanceId: string; controlSessionToken: string; expiresAt: Date}> {
   const controlSessionToken = generateOpaqueToken('runnerControlSession');
   const expiresAt = new Date(Date.now() + params.ttlSeconds * 1000);
-  return await db().transaction(async (tx) => {
+  const result = await db().transaction(async (tx) => {
     const [bootstrap] = await tx
       .update(runnerBootstrapTokens)
       .set({consumedAt: sql`now()`})
@@ -99,6 +155,21 @@ export async function exchangeRunnerBootstrapToken(params: {
       )
       .returning();
     if (!bootstrap) throw new RunnerBootstrapTokenInvalidError();
+    const [runner] = await tx
+      .select({
+        runnerInstanceId: providerRunners.id,
+        createdAt: providerRunners.createdAt,
+        provider: providerRunners.providerKind,
+        launchKind: providerRunners.launchKind,
+      })
+      .from(providerRunners)
+      .where(
+        and(
+          eq(providerRunners.id, bootstrap.runnerInstanceId),
+          eq(providerRunners.provisionerId, bootstrap.provisionerId),
+        ),
+      )
+      .limit(1);
     const [session] = await tx
       .insert(runnerControlSessions)
       .values({
@@ -108,10 +179,28 @@ export async function exchangeRunnerBootstrapToken(params: {
         prefix: extractDisplayPrefix(controlSessionToken),
         expiresAt,
       })
-      .returning({id: runnerControlSessions.id});
+      .returning({createdAt: runnerControlSessions.createdAt});
     if (!session) throw new Error('Runner control session insert returned no row');
-    return {runnerInstanceId: bootstrap.runnerInstanceId, controlSessionToken, expiresAt};
+    return {
+      runner,
+      session,
+      runnerInstanceId: bootstrap.runnerInstanceId,
+      controlSessionToken,
+      expiresAt,
+    };
   });
+  if (result.runner)
+    recordProviderRunnerCreatedToControlSession({
+      durationMilliseconds: result.session.createdAt.getTime() - result.runner.createdAt.getTime(),
+      provider: result.runner.provider,
+      launchKind: result.runner.launchKind,
+      runnerInstanceId: result.runner.runnerInstanceId,
+    });
+  return {
+    runnerInstanceId: result.runnerInstanceId,
+    controlSessionToken: result.controlSessionToken,
+    expiresAt: result.expiresAt,
+  };
 }
 
 export async function resolveRunnerControlSession(rawToken: string) {
@@ -143,7 +232,7 @@ export async function enrollRunnerControlSession(params: {
   providerKind: string;
   protocolVersion: string;
 }): Promise<string | null> {
-  return await db().transaction(async (tx) => {
+  const result = await db().transaction(async (tx) => {
     const [current] = await tx
       .select({
         intendedReservationId: providerRunners.intendedReservationId,
@@ -214,22 +303,38 @@ export async function enrollRunnerControlSession(params: {
     await updateRunnerControlSessionLastSeen(tx, params.runnerInstanceId, params.provisionerId);
 
     const intendedReservationId = updated.intendedReservationId;
-    if (!intendedReservationId) return null;
+    if (!intendedReservationId)
+      return {
+        activationToken: null,
+        controlSessionToAssignment: [],
+        assignmentRejectedReason: null,
+        promotionFailureReason: null,
+      };
 
     try {
-      return await tx.transaction(async (promotionTx) => {
-        await assignRunnerInstancesTx(promotionTx, {
+      const promotion = await tx.transaction(async (promotionTx) => {
+        const assignment = await assignRunnerInstancesTx(promotionTx, {
           provisionerId: params.provisionerId,
           reservationId: intendedReservationId,
           runnerInstanceIds: [params.runnerInstanceId],
+          surface: 'enrollment',
         });
-        return await issueRunnerActivationTokenTx(promotionTx, {
+        const activationToken = await issueRunnerActivationTokenTx(promotionTx, {
           runnerInstanceId: params.runnerInstanceId,
           provisionerId: params.provisionerId,
           ttlSeconds: config.RUNNER_ACTIVATION_TOKEN_TTL_SECONDS,
+          surface: 'enrollment',
         });
+        return {activationToken, controlSessionToAssignment: assignment.controlSessionToAssignment};
       });
+      return {
+        activationToken: promotion.activationToken,
+        controlSessionToAssignment: promotion.controlSessionToAssignment,
+        assignmentRejectedReason: null,
+        promotionFailureReason: null,
+      };
     } catch (error) {
+      const assignmentRejectionReason = getRunnerAssignmentRejectionReason(error);
       const expectedFailureReason = getRunnerReservationPromotionFailureReason(error);
       const details = {
         err: error,
@@ -238,7 +343,6 @@ export async function enrollRunnerControlSession(params: {
         reservationId: intendedReservationId,
       };
       if (expectedFailureReason) {
-        recordRunnerReservationPromotionFailure(expectedFailureReason);
         logger().debug(details, 'Runner reservation could not be promoted during enrollment');
       } else {
         logger().error(
@@ -246,9 +350,27 @@ export async function enrollRunnerControlSession(params: {
           'Unexpected failure promoting runner reservation during enrollment',
         );
       }
-      return null;
+      return {
+        activationToken: null,
+        controlSessionToAssignment: [],
+        assignmentRejectedReason: assignmentRejectionReason,
+        promotionFailureReason: expectedFailureReason,
+      };
     }
   });
+  for (const observation of result.controlSessionToAssignment)
+    recordProviderRunnerControlSessionToAssignment(observation);
+  // These counters intentionally overlap: assignment_rejected records the assignment-facing
+  // reason, while reservation_promotion_failure records the enrollment recovery outcome. They
+  // answer different questions and must not be summed.
+  if (result.assignmentRejectedReason)
+    recordProviderRunnerAssignmentRejected({
+      reason: result.assignmentRejectedReason,
+      surface: 'enrollment',
+    });
+  if (result.promotionFailureReason)
+    recordRunnerReservationPromotionFailure(result.promotionFailureReason);
+  return result.activationToken;
 }
 
 function getRunnerReservationPromotionFailureReason(

package/src/core/runner-instances.test.ts

@@ -54,18 +54,37 @@ describe('reconcileRunnerInstancesFromDbResult', () => {
 
     expect(result[0]?.desiredIntent).toBe('terminate');
   });
+
+  it('returns the intended reservation when a runner is not assigned yet', () => {
+    const intendedReservationId = crypto.randomUUID();
+    const result = reconcileRunnerInstancesFromDbResult({
+      observedRunnerInstanceIds: ['provisioned-runner-1'],
+      observedRows: [
+        providerRunner({providerRunnerId: 'provisioned-runner-1', intendedReservationId}),
+      ],
+      boundJobExecutionsByRunnerInstanceId: new Map(),
+    });
+
+    expect(result[0]).toMatchObject({
+      reservationId: null,
+      intendedReservationId,
+    });
+  });
 });
 
 function providerRunner(params: {
   providerRunnerId: string;
   state?: 'starting' | 'running' | 'stopping' | 'stopped' | 'failed' | 'terminated';
+  intendedReservationId?: string | null;
 }) {
   return {
     id: crypto.randomUUID(),
     workspaceId: crypto.randomUUID(),
     provisionerId: crypto.randomUUID(),
     providerRunnerId: params.providerRunnerId,
+    intendedReservationId: params.intendedReservationId ?? null,
     reservationId: null,
+    launchKind: 'manual' as const,
     templateKey: 'linux',
     labels: ['linux'],
     state: params.state ?? 'running',

package/src/core/runner-instances.ts

@@ -62,6 +62,7 @@ export interface ReconciledBoundJobExecution {
 export interface ReconciledRunnerInstance {
   providerRunnerId: string;
   state: RunnerInstanceState | null;
+  intendedReservationId: string | null;
   reservationId: string | null;
   runnerSessionId: string | null;
   boundJobExecution: ReconciledBoundJobExecution | null;
@@ -157,6 +158,7 @@ export function reconcileRunnerInstancesFromDbResult(params: {
     return {
       providerRunnerId,
       state: row?.state ?? null,
+      intendedReservationId: row?.intendedReservationId ?? null,
       reservationId: row?.reservationId ?? null,
       runnerSessionId: row?.runnerSessionId ?? null,
       boundJobExecution: boundJobExecution

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

@@ -1,9 +1,15 @@
+import {vi} from '@shipfox/vitest/vi';
 import {and, eq} from 'drizzle-orm';
 import {db} from '#db/db.js';
 import {ephemeralRegistrationTokens} from '#db/schema/ephemeral-registration-tokens.js';
 import {runnerActivationTokens} from '#db/schema/runner-activation-tokens.js';
+import type {RunnerInstanceInsertDb} from '#db/schema/runner-instances.js';
 import {providerRunners} from '#db/schema/runner-instances.js';
 import {runnerSessions} from '#db/schema/runner-sessions.js';
+import {
+  type RunnerActivationTokenNotIssuedReason,
+  runnerActivationTokenNotIssuedCount,
+} from '#metrics/instance.js';
 import {
   ephemeralRegistrationTokenFactory,
   getRunnerSessionTokenClaims,
@@ -18,9 +24,34 @@ import {
   RegistrationTokenWorkspaceMismatchError,
   RunnerLabelsReservedError,
 } from './errors.js';
-import {issueRunnerActivationToken} from './runner-activation.js';
+import {getRunnerAssignment, issueRunnerActivationToken} from './runner-activation.js';
 import {registerRunnerSession} from './runner-sessions.js';
 
+const activationTokenNotIssuedCases: Array<{
+  reason: RunnerActivationTokenNotIssuedReason;
+  update: Partial<RunnerInstanceInsertDb>;
+  provisionerId?: string;
+}> = [
+  {reason: 'runner-not-found', update: {}, provisionerId: crypto.randomUUID()},
+  {reason: 'missing-workspace', update: {workspaceId: null}},
+  {reason: 'existing-session', update: {runnerSessionId: crypto.randomUUID()}},
+  {reason: 'not-running', update: {state: 'starting'}},
+];
+
+function activationTokenMetricCalls(spy: {mock: {calls: unknown[][]}}): unknown[][] {
+  // The test setup uses a shared NoopMeter counter, so filter calls to this metric before counting.
+  return spy.mock.calls.filter(([, attributes]) => {
+    if (typeof attributes !== 'object' || attributes === null) return false;
+    const reason = (attributes as {reason?: unknown}).reason;
+    const surface = (attributes as {surface?: unknown}).surface;
+    return (
+      ['runner-not-found', 'missing-workspace', 'existing-session', 'not-running'].includes(
+        String(reason),
+      ) && ['enrollment', 'poll'].includes(String(surface))
+    );
+  });
+}
+
 describe('registerRunnerSession', () => {
   let workspaceId: string;
   let registrationTokenId: string;
@@ -245,11 +276,13 @@ describe('activation runner sessions', () => {
       runnerInstanceId,
       provisionerId,
       ttlSeconds: 60,
+      surface: 'poll',
     });
     const replacementToken = await issueRunnerActivationToken({
       runnerInstanceId,
       provisionerId,
       ttlSeconds: 60,
+      surface: 'poll',
     });
 
     const tokens = await db()
@@ -265,11 +298,97 @@ describe('activation runner sessions', () => {
     expect(tokens.filter((token) => token.revokedAt !== null)).toHaveLength(1);
   });
 
+  it.each(
+    activationTokenNotIssuedCases,
+  )('records $reason when direct activation-token issuance is skipped', async ({
+    reason,
+    update,
+    provisionerId: caseProvisionerId,
+  }) => {
+    const addSpy = vi.spyOn(runnerActivationTokenNotIssuedCount, 'add');
+
+    try {
+      if (Object.keys(update).length > 0) {
+        await db()
+          .update(providerRunners)
+          .set(update)
+          .where(eq(providerRunners.id, runnerInstanceId));
+      }
+
+      const activationToken = await issueRunnerActivationToken({
+        runnerInstanceId,
+        provisionerId: caseProvisionerId ?? provisionerId,
+        ttlSeconds: 60,
+        surface: 'poll',
+      });
+
+      expect(activationToken).toBeNull();
+      expect(activationTokenMetricCalls(addSpy)).toEqual([[1, {reason, surface: 'poll'}]]);
+    } finally {
+      addSpy.mockRestore();
+    }
+  });
+
+  it('does not record a metric when assignment polling finds no assignment', async () => {
+    const addSpy = vi.spyOn(runnerActivationTokenNotIssuedCount, 'add');
+
+    try {
+      await db()
+        .update(providerRunners)
+        .set({workspaceId: null})
+        .where(eq(providerRunners.id, runnerInstanceId));
+
+      const assignment = await getRunnerAssignment({runnerInstanceId, provisionerId});
+
+      expect(assignment).toBeNull();
+      expect(activationTokenMetricCalls(addSpy)).toHaveLength(0);
+    } finally {
+      addSpy.mockRestore();
+    }
+  });
+
+  it('does not poll for an assignment while the runner is not running', async () => {
+    const addSpy = vi.spyOn(runnerActivationTokenNotIssuedCount, 'add');
+
+    try {
+      await db()
+        .update(providerRunners)
+        .set({state: 'starting'})
+        .where(eq(providerRunners.id, runnerInstanceId));
+
+      const assignment = await getRunnerAssignment({runnerInstanceId, provisionerId});
+
+      expect(assignment).toBeNull();
+      expect(activationTokenMetricCalls(addSpy)).toHaveLength(0);
+    } finally {
+      addSpy.mockRestore();
+    }
+  });
+
+  it('does not record a metric when activation-token issuance succeeds', async () => {
+    const addSpy = vi.spyOn(runnerActivationTokenNotIssuedCount, 'add');
+
+    try {
+      const activationToken = await issueRunnerActivationToken({
+        runnerInstanceId,
+        provisionerId,
+        ttlSeconds: 60,
+        surface: 'poll',
+      });
+
+      expect(activationToken).toEqual(expect.any(String));
+      expect(activationTokenMetricCalls(addSpy)).toHaveLength(0);
+    } finally {
+      addSpy.mockRestore();
+    }
+  });
+
   it('allows only one concurrent registration to consume an activation token', async () => {
     const rawToken = await issueRunnerActivationToken({
       runnerInstanceId,
       provisionerId,
       ttlSeconds: 60,
+      surface: 'poll',
     });
     const [activationToken] = await db()
       .select()
@@ -314,6 +433,7 @@ describe('activation runner sessions', () => {
       runnerInstanceId,
       provisionerId,
       ttlSeconds: 60,
+      surface: 'poll',
     });
     const [activationToken] = await db()
       .select()