@shipfox/api-runners 10.1.0 → 11.0.0

package/drizzle/meta/_journal.json

@@ -15,6 +15,20 @@
       "when": 1785161220762,
       "tag": "0001_intended_reservation",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1785232451694,
+      "tag": "0002_special_shadowcat",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1785235910167,
+      "tag": "0003_flaky_sally_floyd",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-runners",
   "license": "MIT",
-  "version": "10.1.0",
+  "version": "11.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -21,9 +21,10 @@
     "@temporalio/workflow": "1.18.1",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "10.1.0",
-    "@shipfox/api-auth-dto": "10.1.0",
-    "@shipfox/api-runners-dto": "10.0.0",
+    "@shipfox/api-common-dto": "9.2.0",
+    "@shipfox/api-auth-context": "11.0.0",
+    "@shipfox/api-auth-dto": "10.2.0",
+    "@shipfox/api-runners-dto": "10.2.0",
     "@shipfox/api-workflows-dto": "10.0.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.2",

package/src/config.test.ts

@@ -1,3 +1,4 @@
+import {RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS} from '@shipfox/api-runners-dto';
 import {vi} from '@shipfox/vitest/vi';
 
 describe('EPHEMERAL_REGISTRATION_TOKEN_TTL_SECONDS validation', () => {
@@ -36,6 +37,16 @@ describe('runner assignment polling defaults', () => {
     vi.resetModules();
     const {config} = await import('#config.js');
     expect(config.RUNNER_ASSIGNMENT_POLL_INTERVAL_MS).toBe(250);
+    expect(config.RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS).toBe(
+      RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS,
+    );
+  });
+
+  it('rejects a zero-second server-side assignment wait cap', async () => {
+    vi.stubEnv('RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS', '0');
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow('RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS');
   });
 });
 describe('REGISTRATION_TOKEN_BATCH_MAX validation', () => {

package/src/config.ts

@@ -1,3 +1,4 @@
+import {RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS} from '@shipfox/api-runners-dto';
 import {bool, createConfig, num} from '@shipfox/config';
 import {STUCK_JOB_THRESHOLD_SECONDS} from '#core/maintenance-policy.js';
 
@@ -19,8 +20,8 @@ export const config = createConfig({
     default: 300,
   }),
   RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS: num({
-    desc: 'Maximum time the runner assignment poll waits before returning no assignment, in seconds.',
-    default: 30,
+    desc: 'Maximum server-side cap for the per-request runner assignment wait, in seconds. Managed runners request their own bounded wait with wait_seconds.',
+    default: RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS,
   }),
   RUNNER_ASSIGNMENT_POLL_INTERVAL_MS: num({
     desc: 'Delay between durable assignment reads while a runner-control session waits for an assignment, in milliseconds.',
@@ -159,12 +160,22 @@ for (const [name, value] of [
   }
 }
 
-for (const [name, value] of [
-  ['RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS', config.RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS],
-  ['RUNNER_ASSIGNMENT_POLL_INTERVAL_MS', config.RUNNER_ASSIGNMENT_POLL_INTERVAL_MS],
-] as const) {
-  if (!Number.isInteger(value) || value < 0)
-    throw new Error(`${name} (${value}) must be a whole number >= 0.`);
+if (
+  !Number.isInteger(config.RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS) ||
+  config.RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS < 1
+) {
+  throw new Error(
+    `RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS (${config.RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS}) must be a whole number >= 1.`,
+  );
+}
+
+if (
+  !Number.isInteger(config.RUNNER_ASSIGNMENT_POLL_INTERVAL_MS) ||
+  config.RUNNER_ASSIGNMENT_POLL_INTERVAL_MS < 0
+) {
+  throw new Error(
+    `RUNNER_ASSIGNMENT_POLL_INTERVAL_MS (${config.RUNNER_ASSIGNMENT_POLL_INTERVAL_MS}) must be a whole number >= 0.`,
+  );
 }
 
 if (

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

@@ -0,0 +1,125 @@
+import {config} from '#config.js';
+import {
+  type AdministratorRunnerInstanceRow,
+  type ListAdministratorRunnerInstancesParams,
+  listAdministratorRunnerInstances as listAdministratorRunnerInstanceRows,
+} from '#db/admin-runner-instances.js';
+import {isTerminalState} from '#db/runner-instances.js';
+
+export type RunnerAdministratorLifecycleState =
+  | 'unassigned'
+  | 'assigned'
+  | 'activated'
+  | 'claimed'
+  | 'completed';
+export type RunnerAdministratorEnrollmentState = 'pending' | 'enrolled' | 'activated';
+export type RunnerAdministratorReconciliationStatus = 'current' | 'stale' | 'terminal' | 'unknown';
+
+export interface RunnerAdministratorInstance {
+  id: string;
+  lifecycleState: RunnerAdministratorLifecycleState;
+  computeState: AdministratorRunnerInstanceRow['state'];
+  enrollmentState: RunnerAdministratorEnrollmentState;
+  assignmentPresence: 'assigned' | 'unassigned';
+  assignedWorkspace: {id: string} | null;
+  labels: string[];
+  createdAt: Date;
+  lastHeartbeatAt: Date;
+  closureReason: string | null;
+  closedAt: Date | null;
+  provisioner: {
+    id: string;
+    scope: 'installation';
+    name: string | null;
+  };
+  reconciliationStatus: RunnerAdministratorReconciliationStatus;
+}
+
+export interface ListRunnerAdministratorInstancesParams
+  extends ListAdministratorRunnerInstancesParams {
+  reconciliationStaleAfterSeconds?: number | undefined;
+}
+
+export interface ListRunnerAdministratorInstancesResult {
+  runners: RunnerAdministratorInstance[];
+  nextCursor: Awaited<ReturnType<typeof listAdministratorRunnerInstanceRows>>['nextCursor'];
+}
+
+export async function listRunnerAdministratorInstances(
+  params: ListRunnerAdministratorInstancesParams,
+): Promise<ListRunnerAdministratorInstancesResult> {
+  const result = await listAdministratorRunnerInstanceRows(params);
+  const staleAfterSeconds =
+    params.reconciliationStaleAfterSeconds ??
+    config.RUNNER_STALE_PROVISIONED_RUNNER_THRESHOLD_SECONDS;
+  const now = new Date();
+
+  return {
+    runners: result.runners.map((row) =>
+      toRunnerAdministratorInstance(row, {now, staleAfterSeconds}),
+    ),
+    nextCursor: result.nextCursor,
+  };
+}
+
+function toRunnerAdministratorInstance(
+  row: AdministratorRunnerInstanceRow,
+  params: {now: Date; staleAfterSeconds: number},
+): RunnerAdministratorInstance {
+  const isAssigned = row.workspaceId !== null;
+  const isActivated = row.runnerSessionId !== null;
+  const hasClaim = row.firstClaimedAt !== null;
+  const isTerminal = isTerminalState(row.state);
+
+  return {
+    id: row.id,
+    lifecycleState: !isAssigned
+      ? 'unassigned'
+      : isTerminal
+        ? 'completed'
+        : !isActivated
+          ? 'assigned'
+          : !hasClaim
+            ? 'activated'
+            : 'claimed',
+    computeState: row.state,
+    enrollmentState: isActivated
+      ? 'activated'
+      : row.hasActiveControlSession
+        ? 'enrolled'
+        : 'pending',
+    assignmentPresence: isAssigned ? 'assigned' : 'unassigned',
+    assignedWorkspace: row.workspaceId ? {id: row.workspaceId} : null,
+    labels: row.labels,
+    createdAt: row.createdAt,
+    lastHeartbeatAt: row.reportedAt,
+    closureReason: row.reason,
+    closedAt: closedAt(row),
+    provisioner: {
+      id: row.provisionerId,
+      scope: 'installation',
+      name: row.provisionerName,
+    },
+    reconciliationStatus: reconciliationStatus(row, params),
+  };
+}
+
+function closedAt(row: AdministratorRunnerInstanceRow): Date | null {
+  if (row.state === 'stopped') return row.stoppedAt;
+  if (row.state === 'failed') return row.failedAt;
+  if (row.state === 'terminated') return row.terminatedAt;
+  return null;
+}
+
+function reconciliationStatus(
+  row: AdministratorRunnerInstanceRow,
+  params: {now: Date; staleAfterSeconds: number},
+): RunnerAdministratorReconciliationStatus {
+  if (isTerminalState(row.state)) return 'terminal';
+  if (!row.provisionerLastSeenAt) return 'unknown';
+
+  const cutoff = params.now.getTime() - params.staleAfterSeconds * 1000;
+  const reportIsStale = row.reportedAt.getTime() <= cutoff;
+  const provisionerIsStale = row.provisionerLastSeenAt.getTime() <= cutoff;
+  return reportIsStale || provisionerIsStale ? 'stale' : 'current';
+}

package/src/core/errors.ts

@@ -19,6 +19,20 @@ export class ProvisionerTokenNotFoundError extends Error {
   }
 }
 
+export class ProvisionerAdminIdempotencyKeyReuseError extends Error {
+  constructor() {
+    super('Idempotency-Key was already used for a different provisioner token command');
+    this.name = 'ProvisionerAdminIdempotencyKeyReuseError';
+  }
+}
+
+export class ProvisionerAdminIdempotencyReplayUnavailableError extends Error {
+  constructor() {
+    super('Idempotency-Key replay cannot reproduce the original provisioner token');
+    this.name = 'ProvisionerAdminIdempotencyReplayUnavailableError';
+  }
+}
+
 export class EmptyRunnerLabelsError extends Error {
   constructor() {
     super('Runner labels cannot be empty');

package/src/core/index.ts

@@ -1,3 +1,9 @@
+export {
+  type ListRunnerAdministratorInstancesParams,
+  type ListRunnerAdministratorInstancesResult,
+  listRunnerAdministratorInstances,
+  type RunnerAdministratorInstance,
+} from './admin-runner-instances.js';
 export type {EphemeralRegistrationToken} from './entities/ephemeral-registration-token.js';
 export type {ManualRegistrationToken} from './entities/manual-registration-token.js';
 export type {ProvisionerCapabilitySnapshot} from './entities/provisioner-capability-snapshot.js';
@@ -14,6 +20,8 @@ export type {RunnerSession} from './entities/runner-session.js';
 export {
   EmptyRunnerLabelsError,
   ManualRegistrationTokenNotFoundError,
+  ProvisionerAdminIdempotencyKeyReuseError,
+  ProvisionerAdminIdempotencyReplayUnavailableError,
   ProvisionerTokenNotFoundError,
   RegistrationTokenConsumedError,
   RegistrationTokenExpiredError,
@@ -28,10 +36,14 @@ export {
 } from './manual-registration-tokens.js';
 export {hasActiveWorkspaceProvisionerCapability} from './provisioner-capability-snapshots.js';
 export {
+  createAdministratorInstallationProvisionerToken,
   createInstallationProvisionerToken,
   createWorkspaceProvisionerToken,
+  installationProvisionerTokenStatus,
   listActiveProvisioners,
+  listAdministratorInstallationProvisionerTokens,
   listUsableProvisionerTokens,
+  revokeAdministratorInstallationProvisionerToken,
   revokeInstallationProvisionerToken,
   revokeWorkspaceProvisionerToken,
 } from './provisioner-tokens.js';

package/src/core/provisioner-tokens.ts

@@ -1,14 +1,25 @@
+import {createHmac} from 'node:crypto';
+import type {AdministrationRole} from '@shipfox/api-common-dto';
+import {createAdministrationActionEvent} from '@shipfox/api-common-dto';
+import {runnerSessionTokenKey} from '@shipfox/node-auth-root-key';
+import type {TimestampIdCursor} from '@shipfox/node-drizzle';
 import {extractDisplayPrefix, generateOpaqueToken, hashOpaqueToken} from '@shipfox/node-tokens';
 import {
+  createInstallationProvisionerTokenWithAudit,
   createProvisionerToken,
   listActiveProvisionerTokens,
+  listInstallationProvisionerTokens,
   listUsableProvisionerTokensByWorkspaceId,
   revokeInstallationProvisionerToken as revokeInstallationProvisionerTokenDb,
+  revokeInstallationProvisionerTokenWithAudit,
   revokeProvisionerToken,
 } from '#db/provisioner-tokens.js';
 import {config} from '../config.js';
 import type {ActiveProvisionerToken, ProvisionerToken} from './entities/provisioner-token.js';
-import {ProvisionerTokenNotFoundError} from './errors.js';
+import {
+  ProvisionerAdminIdempotencyReplayUnavailableError,
+  ProvisionerTokenNotFoundError,
+} from './errors.js';
 
 export interface CreateWorkspaceProvisionerTokenParams {
   workspaceId: string;
@@ -92,3 +103,148 @@ export async function revokeInstallationProvisionerToken(params: {
   if (!token) throw new ProvisionerTokenNotFoundError(params.tokenId);
   return token;
 }
+
+const ADMIN_OWNER_ROLE: AdministrationRole = 'admin-owner';
+const ADMIN_OPERATOR_ROLE: AdministrationRole = 'admin-operator';
+const CREATE_ADMIN_COMMAND = 'runners.provisioner_token.create';
+const REVOKE_ADMIN_COMMAND = 'runners.provisioner_token.revoke';
+
+export interface InstallationProvisionerTokenAdministrationContext {
+  actorId: string;
+  actorRole: AdministrationRole;
+  idempotencyKey: string;
+  correlationId: string;
+  reason: string;
+}
+
+function administrationCommandFingerprint(command: string, input: unknown): string {
+  return hashOpaqueToken(`${command}:${JSON.stringify(input)}`);
+}
+
+function idempotentProvisionerToken(seed: string): string {
+  const generated = generateOpaqueToken('provisionerToken');
+  const tokenPrefix = generated.slice(0, -43);
+  const key = createHmac('sha256', runnerSessionTokenKey())
+    .update('shipfox/provisioner-token-idempotency/v1')
+    .digest();
+  const suffix = createHmac('sha256', key).update(seed).digest('base64url');
+  return `${tokenPrefix}${suffix}`;
+}
+
+function administrationEvent(params: {
+  actorId: string;
+  actorRole: AdministrationRole;
+  requiredRole: AdministrationRole;
+  command: string;
+  targetId: string;
+  reason: string;
+  correlationId: string;
+  idempotencyKeyFingerprint: string;
+}) {
+  return createAdministrationActionEvent({
+    actorId: params.actorId,
+    actorRole: params.actorRole,
+    requiredRole: params.requiredRole,
+    command: params.command,
+    targetType: 'provisioner-token',
+    targetId: params.targetId,
+    reason: params.reason,
+    result: 'succeeded',
+    correlationId: params.correlationId,
+    idempotencyKeyFingerprint: params.idempotencyKeyFingerprint,
+    occurredAt: new Date().toISOString(),
+  });
+}
+
+export type InstallationProvisionerTokenStatus = 'active' | 'expired' | 'revoked';
+
+export function installationProvisionerTokenStatus(
+  token: ProvisionerToken,
+  now = new Date(),
+): InstallationProvisionerTokenStatus {
+  if (token.revokedAt) return 'revoked';
+  if (token.expiresAt && token.expiresAt <= now) return 'expired';
+  return 'active';
+}
+
+export async function listAdministratorInstallationProvisionerTokens(params: {
+  limit: number;
+  cursor?: TimestampIdCursor | undefined;
+  status?: InstallationProvisionerTokenStatus | undefined;
+}) {
+  return await listInstallationProvisionerTokens(params);
+}
+
+export async function createAdministratorInstallationProvisionerToken(
+  params: InstallationProvisionerTokenAdministrationContext & {
+    name?: string | undefined;
+    ttlSeconds?: number | undefined;
+  },
+): Promise<{token: ProvisionerToken; rawToken: string; correlationId: string}> {
+  const idempotencyKeyFingerprint = hashOpaqueToken(params.idempotencyKey);
+  const requestFingerprint = administrationCommandFingerprint(CREATE_ADMIN_COMMAND, {
+    name: params.name,
+    ttlSeconds: params.ttlSeconds,
+    reason: params.reason,
+  });
+  const rawToken = idempotentProvisionerToken(
+    `${params.actorId}:${params.idempotencyKey}:${requestFingerprint}`,
+  );
+  const result = await createInstallationProvisionerTokenWithAudit({
+    actorId: params.actorId,
+    command: CREATE_ADMIN_COMMAND,
+    correlationId: params.correlationId,
+    idempotencyKeyFingerprint,
+    requestFingerprint,
+    hashedToken: hashOpaqueToken(rawToken),
+    prefix: extractDisplayPrefix(rawToken),
+    name: params.name,
+    ttlSeconds: params.ttlSeconds,
+    event: (tokenId) =>
+      administrationEvent({
+        actorId: params.actorId,
+        actorRole: params.actorRole,
+        requiredRole: ADMIN_OWNER_ROLE,
+        command: CREATE_ADMIN_COMMAND,
+        targetId: tokenId,
+        reason: params.reason,
+        correlationId: params.correlationId,
+        idempotencyKeyFingerprint,
+      }),
+  });
+  if (result.replayed && hashOpaqueToken(rawToken) !== result.token.hashedToken) {
+    throw new ProvisionerAdminIdempotencyReplayUnavailableError();
+  }
+  return {...result, rawToken, correlationId: result.correlationId};
+}
+
+export async function revokeAdministratorInstallationProvisionerToken(
+  params: InstallationProvisionerTokenAdministrationContext & {tokenId: string},
+): Promise<{token: ProvisionerToken; correlationId: string}> {
+  const idempotencyKeyFingerprint = hashOpaqueToken(params.idempotencyKey);
+  const requestFingerprint = administrationCommandFingerprint(REVOKE_ADMIN_COMMAND, {
+    tokenId: params.tokenId,
+    reason: params.reason,
+  });
+  const result = await revokeInstallationProvisionerTokenWithAudit({
+    tokenId: params.tokenId,
+    actorId: params.actorId,
+    command: REVOKE_ADMIN_COMMAND,
+    correlationId: params.correlationId,
+    idempotencyKeyFingerprint,
+    requestFingerprint,
+    event: (tokenId) =>
+      administrationEvent({
+        actorId: params.actorId,
+        actorRole: params.actorRole,
+        requiredRole: ADMIN_OPERATOR_ROLE,
+        command: REVOKE_ADMIN_COMMAND,
+        targetId: tokenId,
+        reason: params.reason,
+        correlationId: params.correlationId,
+        idempotencyKeyFingerprint,
+      }),
+  });
+  if (!result) throw new ProvisionerTokenNotFoundError(params.tokenId);
+  return result;
+}

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

@@ -0,0 +1,121 @@
+import {type TimestampIdCursor, timestampIdCursorWhere} from '@shipfox/node-drizzle';
+import {canonicalizeLabels} from '@shipfox/runner-labels';
+import {
+  and,
+  arrayContains,
+  desc,
+  eq,
+  exists,
+  gt,
+  isNotNull,
+  isNull,
+  type SQL,
+  sql,
+} from 'drizzle-orm';
+import type {RunnerInstanceState} from '#core/entities/runner-instance.js';
+import {db} from './db.js';
+import {provisionerTokens} from './schema/provisioner-tokens.js';
+import {runnerControlSessions} from './schema/runner-control-sessions.js';
+import {providerRunners} from './schema/runner-instances.js';
+
+export type AdministratorRunnerAssignmentFilter = 'assigned' | 'unassigned';
+
+export interface AdministratorRunnerInstanceRow {
+  id: string;
+  workspaceId: string | null;
+  state: RunnerInstanceState;
+  labels: string[];
+  runnerSessionId: string | null;
+  firstClaimedAt: Date | null;
+  hasActiveControlSession: boolean;
+  reason: string | null;
+  reportedAt: Date;
+  stoppedAt: Date | null;
+  failedAt: Date | null;
+  terminatedAt: Date | null;
+  createdAt: Date;
+  provisionerId: string;
+  provisionerName: string | null;
+  provisionerLastSeenAt: Date | null;
+}
+
+export interface ListAdministratorRunnerInstancesParams {
+  limit: number;
+  cursor?: TimestampIdCursor | undefined;
+  state?: RunnerInstanceState | undefined;
+  assignment?: AdministratorRunnerAssignmentFilter | undefined;
+  label?: string | undefined;
+}
+
+export interface ListAdministratorRunnerInstancesResult {
+  runners: AdministratorRunnerInstanceRow[];
+  nextCursor: TimestampIdCursor | null;
+}
+
+export async function listAdministratorRunnerInstances(
+  params: ListAdministratorRunnerInstancesParams,
+): Promise<ListAdministratorRunnerInstancesResult> {
+  const conditions: SQL[] = [eq(provisionerTokens.scope, 'installation')];
+  const cursor = timestampIdCursorWhere({
+    timestampColumn: providerRunners.createdAt,
+    idColumn: providerRunners.id,
+    cursor: params.cursor,
+  });
+
+  if (cursor) conditions.push(cursor);
+  if (params.state) conditions.push(eq(providerRunners.state, params.state));
+  if (params.assignment === 'assigned') conditions.push(isNotNull(providerRunners.workspaceId));
+  if (params.assignment === 'unassigned') conditions.push(isNull(providerRunners.workspaceId));
+  if (params.label) {
+    const [label] = canonicalizeLabels(params.label);
+    if (label) conditions.push(arrayContains(providerRunners.labels, [label]));
+  }
+
+  const rows = await db()
+    .select({
+      id: providerRunners.id,
+      workspaceId: providerRunners.workspaceId,
+      state: providerRunners.state,
+      labels: providerRunners.labels,
+      runnerSessionId: providerRunners.runnerSessionId,
+      firstClaimedAt: providerRunners.firstClaimedAt,
+      hasActiveControlSession: exists(
+        db()
+          .select({id: runnerControlSessions.id})
+          .from(runnerControlSessions)
+          .where(
+            and(
+              eq(runnerControlSessions.runnerInstanceId, providerRunners.id),
+              isNull(runnerControlSessions.closedAt),
+              gt(runnerControlSessions.expiresAt, sql`now()`),
+            ),
+          ),
+      ),
+      reason: providerRunners.reason,
+      reportedAt: providerRunners.reportedAt,
+      stoppedAt: providerRunners.stoppedAt,
+      failedAt: providerRunners.failedAt,
+      terminatedAt: providerRunners.terminatedAt,
+      createdAt: providerRunners.createdAt,
+      provisionerId: provisionerTokens.id,
+      provisionerName: provisionerTokens.name,
+      provisionerLastSeenAt: provisionerTokens.lastSeenAt,
+    })
+    .from(providerRunners)
+    .innerJoin(provisionerTokens, eq(provisionerTokens.id, providerRunners.provisionerId))
+    .where(and(...conditions))
+    .orderBy(desc(providerRunners.createdAt), desc(providerRunners.id))
+    .limit(params.limit + 1);
+
+  const hasMore = rows.length > params.limit;
+  const pageRows = hasMore ? rows.slice(0, params.limit) : rows;
+  const last = pageRows.at(-1);
+
+  return {
+    runners: pageRows.map((row) => ({
+      ...row,
+      hasActiveControlSession: Boolean(row.hasActiveControlSession),
+    })),
+    nextCursor: hasMore && last ? {createdAt: last.createdAt, id: last.id} : null,
+  };
+}

package/src/db/db.ts

@@ -1,5 +1,6 @@
 import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
 import {pgClient} from '@shipfox/node-postgres';
+import {runnersAdminCommandResults} from './schema/admin-command-results.js';
 import {ephemeralRegistrationTokens} from './schema/ephemeral-registration-tokens.js';
 import {manualRegistrationTokens} from './schema/manual-registration-tokens.js';
 import {runnersOutbox} from './schema/outbox.js';
@@ -15,6 +16,7 @@ import {runnerSessions} from './schema/runner-sessions.js';
 import {runningJobExecutions} from './schema/running-job-executions.js';
 
 export const schema = {
+  runnersAdminCommandResults,
   ephemeralRegistrationTokens,
   pendingJobExecutions,
   providerRunners,

package/src/db/index.ts

@@ -1,6 +1,13 @@
 import {dirname, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
 
+export type {
+  AdministratorRunnerAssignmentFilter,
+  AdministratorRunnerInstanceRow,
+  ListAdministratorRunnerInstancesParams,
+  ListAdministratorRunnerInstancesResult,
+} from './admin-runner-instances.js';
+export {listAdministratorRunnerInstances} from './admin-runner-instances.js';
 export {closeDb, db, schema} from './db.js';
 export type {
   CreateEphemeralRegistrationTokenParams,
@@ -44,10 +51,13 @@ export {
 } from './provisioner-capability-snapshots.js';
 export type {CreateProvisionerTokenParams} from './provisioner-tokens.js';
 export {
+  createInstallationProvisionerTokenWithAudit,
   createProvisionerToken,
   listActiveProvisionerTokens,
+  listInstallationProvisionerTokens,
   listUsableProvisionerTokensByWorkspaceId,
   resolveProvisionerTokenByHash,
+  revokeInstallationProvisionerTokenWithAudit,
   revokeProvisionerToken,
   touchProvisionerLastSeen,
 } from './provisioner-tokens.js';

package/src/db/job-executions.test.ts

@@ -27,6 +27,7 @@ import {
 } from './job-executions.js';
 import {runnersOutbox} from './schema/outbox.js';
 import {pendingJobExecutions} from './schema/pending-job-executions.js';
+import {providerRunners} from './schema/runner-instances.js';
 import {runnerSessions} from './schema/runner-sessions.js';
 import {runningJobExecutions} from './schema/running-job-executions.js';
 
@@ -408,10 +409,20 @@ describe('claimPendingJobExecution', () => {
   it('does not spend a claim when a capped session polls an empty queue', async () => {
     const provisionerId = crypto.randomUUID();
     const providerRunnerId = `provisioned-runner-${crypto.randomUUID()}`;
+    const runnerInstanceId = crypto.randomUUID();
     await db()
       .update(runnerSessions)
       .set({registrationTokenKind: 'ephemeral', maxClaims: 1, provisionerId, providerRunnerId})
       .where(eq(runnerSessions.id, runnerSessionId));
+    await db().insert(providerRunners).values({
+      id: runnerInstanceId,
+      workspaceId,
+      provisionerId,
+      providerRunnerId,
+      labels: sessionLabels,
+      state: 'running',
+      reportedAt: new Date(),
+    });
 
     const empty = await claimPendingJobExecution({workspaceId, runnerSessionId, maxClaims: 1});
 
@@ -431,6 +442,12 @@ describe('claimPendingJobExecution', () => {
       .where(eq(runnerSessions.id, runnerSessionId));
     expect(claimed?.jobId).toBe(created.jobId);
     expect(afterClaim?.claimsUsed).toBe(1);
+
+    const [runner] = await db()
+      .select({firstClaimedAt: providerRunners.firstClaimedAt})
+      .from(providerRunners)
+      .where(eq(providerRunners.id, runnerInstanceId));
+    expect(runner?.firstClaimedAt).toBeInstanceOf(Date);
   });
 
   it('allows a manual session to claim repeatedly', async () => {