@vzn/vx-dte 0.0.0 → 0.0.650

package/src/github.ts

@@ -0,0 +1,523 @@
+// `github()`: workers as jobs of one workflow the run dispatches per wave
+// (design dte-2026-10.md, "Adapters"): `workflow_dispatch` with the run,
+// the relay, the commit, a size and the workers of that size, which the
+// workflow runs as a matrix on the runners it names for the size. Workers
+// prove themselves by their OIDC identity: the run makes no secret.
+
+import { readFileSync } from 'node:fs'
+import { appendFile } from 'node:fs/promises'
+import path from 'node:path'
+import { refuseUnknownOptions, secretNamed, UserError, ui, type PluginOptionKinds } from '@vzn/vx'
+import type { WorkerSpawn, DteAdapter } from './plugin.js'
+import { printable } from './printable.js'
+
+export interface GithubOptions {
+  /** The workers' workflow file in `.github/workflows` (default `vx-worker.yml`). */
+  readonly workflow?: string
+  /** The runner label of each size, by size name, which `vx dte init` writes; absent, its platform's GitHub-hosted runner. */
+  readonly runsOn?: Readonly<Record<string, string>>
+  /**
+   * Variables the run hands its workers, as the workflow's `env` input (a
+   * JSON object): a value the run's job decides, such as a server's URL
+   * for this commit. An undefined one is left out.
+   */
+  readonly env?: Readonly<Record<string, string | undefined>>
+}
+
+interface Job {
+  readonly name: string
+  readonly status: string
+  readonly conclusion: string | null
+  readonly steps?: readonly { name: string; conclusion: string | null }[]
+}
+
+const KEYS: PluginOptionKinds<GithubOptions> = {
+  workflow: 'string',
+  runsOn: 'object',
+  env: 'object',
+}
+
+/** In `RUNNER_TEMP`: one dispatched workflow run's API path per line. */
+const RUNS_FILE = 'vx-dte-runs'
+
+/**
+ * In `RUNNER_TEMP`: the worker runs a step dispatched before the run began,
+ * one per line, `<API path> <worker>,<worker>`: they start while the job
+ * checks out and installs (`adopt`).
+ */
+const STARTED_FILE = 'vx-dte-started'
+
+/**
+ * A dispatched run's jobs are first read this soon, then twice as late each
+ * time, up to `WATCH_MAX_MS`. Every job of a repository shares
+ * GITHUB_TOKEN's API limit (1000 an hour): at 10 s, a dozen runs at once
+ * spent it, and dispatches and cancels were refused (2026-10-28).
+ */
+const WATCH_FIRST_MS = 2_000
+const WATCH_MAX_MS = 30_000
+
+/** A dispatch the API limit refused waits for its reset only this long: the worker is `starting` meanwhile. */
+const DISPATCH_WAIT_MS = 5 * 60_000
+
+/**
+ * A cancel the API limit refused waits for its reset only this long: a
+ * worker run left queued starts for no one, then reads its run is over
+ * and cancels itself (the workflow's first step, `parent`).
+ */
+const CANCEL_WAIT_MS = 60_000
+
+/** When a refused answer's API limit resets (epoch ms), or undefined for a refusal that is no limit. */
+function limitReset(res: Response): number | undefined {
+  if (res.status !== 403 && res.status !== 429) return undefined
+  const after = res.headers.get('retry-after')
+  if (after !== null && Number.isFinite(Number(after))) return Date.now() + Number(after) * 1000
+  const reset = res.headers.get('x-ratelimit-reset')
+  if (
+    res.headers.get('x-ratelimit-remaining') === '0' &&
+    reset !== null &&
+    Number.isFinite(Number(reset))
+  )
+    return Number(reset) * 1000
+  return undefined
+}
+
+const resetsAt = (at: number): string =>
+  `; the repository's API limit resets at ${new Date(at).toISOString()}`
+
+/** The jobs a matrix makes in one workflow run at most: one dispatch's workers. */
+const MATRIX_MAX = 256
+
+export function github(options: GithubOptions = {}): DteAdapter {
+  refuseUnknownOptions('github()', options, KEYS)
+  const workflow = options.workflow ?? 'vx-worker.yml'
+  // GitHub reads no workflow in a subdirectory, and `vx dte init` writes
+  // the run's own ci.yml beside it: the same name wrote one over the other.
+  if (workflow === '' || workflow.includes('/') || workflow === 'ci.yml')
+    throw new UserError(
+      `github() option "workflow" must be a file name in .github/workflows other than ci.yml, such as vx-worker.yml, got ${JSON.stringify(workflow)}`,
+    )
+  const handed = handedEnv(options.env ?? {})
+  // The workers one demand starts, by size: one dispatch each.
+  const waves = new Map<string, WorkerSpawn[]>()
+  // The workflow runs dispatched, and the dispatches still in flight: a
+  // run that ends first cancels those still queued, or they hold runners
+  // (macOS: five a plan) that the next run's workers wait for.
+  const runs: string[] = []
+  const pending = new Set<Promise<void>>()
+  // A job that fails before its worker joins (checkout, install) told the
+  // run nothing: its worker stayed `starting`, held its size's `max`, and a
+  // run with no other worker waited for the job's timeout (2026-10-22).
+  // Each job is named for its worker; one that ends badly says so.
+  const watched = new Map<string, Map<string, WorkerSpawn>>()
+  let watch: ReturnType<typeof setTimeout> | undefined
+  let closed = false
+  // Each run's jobs answer's ETag: asked with it, an unchanged answer is a
+  // 304, which the API limit does not count.
+  const etags = new Map<string, string>()
+  // No jobs are asked before this (epoch ms): the API limit is spent.
+  let held = 0
+  // The workflow runs whose jobs are this run's workers, by id: a run's id
+  // is a dispatch input anyone who reads the repository's Actions sees, so
+  // a job of any other run is no worker of it.
+  const workerRuns = new Set<string>()
+  // Workers the run no longer needs: a run of only these is cancelled.
+  const cancelled = new Set<string>()
+  // A poll or cancel that failed is said, each cause once (2026-10-23: no
+  // fault is silent): a job that ended badly went unseen, a run held runners.
+  let warn = (m: string): void => ui.say('warn', m)
+  const said = new Set<string>()
+  const runOf = (run: string): string => `workflow run ${run.slice(run.lastIndexOf('/') + 1)}`
+  const failed = (what: string, why: string): void => {
+    const m = `[vx] github(): ${what} failed: ${why}`
+    if (said.has(m)) return
+    said.add(m)
+    warn(m)
+  }
+  /**
+   * A cancel's answer: 202, or 409 for a run already finished; anything
+   * else is said. One the spent API limit refused is asked again at its
+   * reset, when that comes within `CANCEL_WAIT_MS`.
+   */
+  const cancelOf = async (run: string): Promise<void> => {
+    const end = Date.now() + CANCEL_WAIT_MS
+    for (;;) {
+      const res = await call(`${run}/cancel`, { method: 'POST' }).catch((err: unknown) => {
+        failed(`cancelling ${runOf(run)}`, err instanceof Error ? err.message : String(err))
+        return undefined
+      })
+      if (res === undefined || res.ok || res.status === 409) return
+      // quiet: the status is said below either way; the body only adds to it
+      const text = printable((await res.text().catch(() => '')).slice(0, 200))
+      const reset = limitReset(res)
+      if (reset !== undefined && reset <= end) {
+        await Bun.sleep(Math.max(0, reset - Date.now()))
+        continue
+      }
+      failed(
+        `cancelling ${runOf(run)}`,
+        `${res.status} ${text}${reset === undefined ? '' : resetsAt(reset)}`,
+      )
+      return
+    }
+  }
+  // A worker `cancel` was asked to stop, until it is known whether it was:
+  // true when it was left running (`cancel`'s answer).
+  const deciding = new Map<string, (left: boolean) => void>()
+  // Workers whose dispatch has not answered yet.
+  const flying = new Set<string>()
+  // Of `cancelled`, those given up as late: stuck or queued, stopped whatever their job holds.
+  const late = new Set<string>()
+  const decide = (id: string, left: boolean): void => {
+    deciding.get(id)?.(left)
+    deciding.delete(id)
+  }
+  /**
+   * Whether a job of `run` has a runner: its worker's setup is paid, and
+   * a cancel only races its join. Read fresh, past the poll's ETag, which
+   * it leaves alone; undefined when GitHub does not answer.
+   */
+  const hasRunner = async (run: string): Promise<boolean | undefined> => {
+    const res = await call(`${run}/jobs?per_page=100`).catch((err: unknown) => {
+      failed(`reading ${runOf(run)}'s jobs`, err instanceof Error ? err.message : String(err))
+      return undefined
+    })
+    if (res === undefined) return undefined
+    if (!res.ok) {
+      failed(
+        `reading ${runOf(run)}'s jobs`,
+        `${res.status} ${printable((await res.text().catch(() => '')).slice(0, 200))}`,
+      )
+      return undefined
+    }
+    // quiet: an answer that is no JSON leaves the run to be cancelled, as before it was read
+    const body = (await res.json().catch(() => undefined)) as { jobs?: Job[] } | null | undefined
+    if (!Array.isArray(body?.jobs)) return undefined
+    return body.jobs.some((j) => j.status === 'in_progress')
+  }
+  /**
+   * Cancels `run` once none of its workers is still needed and none of its
+   * jobs has a runner. Otherwise it goes on, and each worker let go in it
+   * is left running: it joins, and the run takes it (2026-10-29: small#3,
+   * let go with its job running, joined to be told to exit while two tasks
+   * waited for a core).
+   */
+  const letGo = (run: string, workers: Map<string, WorkerSpawn>): void => {
+    const ids = [...workers.keys()]
+    if (!ids.every((id) => cancelled.has(id))) {
+      for (const id of ids)
+        if (late.has(id)) decide(id, false)
+        else if (cancelled.delete(id)) decide(id, true)
+      return
+    }
+    watched.delete(run)
+    // Let go already (a cancel while its dispatch wrote RUNNER_TEMP).
+    const i = runs.indexOf(run)
+    if (i < 0) return
+    runs.splice(i, 1)
+    const p = (ids.some((id) => late.has(id)) ? Promise.resolve(false) : hasRunner(run))
+      .then((held) => {
+        if (held === true && !closed) {
+          runs.push(run)
+          watched.set(run, workers)
+          if (watch === undefined) look(WATCH_FIRST_MS)
+          for (const id of ids) {
+            cancelled.delete(id)
+            decide(id, true)
+          }
+          return
+        }
+        for (const id of ids) decide(id, false)
+        return cancelOf(run)
+      })
+      .finally(() => pending.delete(p))
+    pending.add(p)
+  }
+  /**
+   * Every page of `run`'s jobs: a wave of more than 100 workers is a run of
+   * more than 100 jobs. Undefined when unread, or when a one-page run has
+   * not changed since the last read (a 304 costs no API limit).
+   */
+  const jobsOf = async (run: string): Promise<Job[] | undefined> => {
+    const all: Job[] = []
+    for (let page = 1; ; page++) {
+      const tag = page === 1 ? etags.get(run) : undefined
+      const res = await call(
+        `${run}/jobs?per_page=100&page=${page}`,
+        tag === undefined ? {} : { headers: { 'if-none-match': tag } },
+      ).catch((err: unknown) => {
+        failed(`reading ${runOf(run)}'s jobs`, err instanceof Error ? err.message : String(err))
+        return undefined
+      })
+      if (res === undefined || res.status === 304) return undefined
+      if (!res.ok) {
+        const reset = limitReset(res)
+        if (reset !== undefined) held = Math.max(held, reset)
+        failed(
+          `reading ${runOf(run)}'s jobs`,
+          `${res.status} ${printable((await res.text().catch(() => '')).slice(0, 200))}${reset === undefined ? '' : resetsAt(reset)}`,
+        )
+        return undefined
+      }
+      const body = (await res.json().catch((err: unknown) => {
+        failed(
+          `reading ${runOf(run)}'s jobs`,
+          `no JSON: ${err instanceof Error ? err.message : String(err)}`,
+        )
+        return undefined
+      })) as { jobs?: Job[] } | null | undefined
+      if (body === undefined) return undefined
+      const jobs = body?.jobs ?? []
+      all.push(...jobs)
+      // A first page's tag says nothing of the next: only a run of one page is asked by it.
+      const etag = res.headers.get('etag')
+      if (page === 1 && etag !== null && jobs.length < 100) etags.set(run, etag)
+      else etags.delete(run)
+      if (jobs.length < 100) return all
+    }
+  }
+  const look = (ms: number): void => {
+    watch = setTimeout(() => {
+      void Promise.all(
+        [...watched].map(async ([run, workers]) => {
+          const jobs = await jobsOf(run)
+          if (jobs === undefined) return
+          for (const j of jobs) {
+            const a = workers.get(j.name)
+            if (a === undefined || j.status !== 'completed') continue
+            workers.delete(j.name)
+            if (closed || cancelled.has(j.name)) continue
+            // A success too: a worker that found no live run left at once,
+            // and the run must not wait on it (2026-10-23).
+            const step = j.steps?.find((x) => x.conclusion === 'failure')?.name
+            a.exited(`job ${j.conclusion}${step === undefined ? '' : ` at ${step}`}`)
+          }
+          if (workers.size === 0) watched.delete(run)
+        }),
+      ).then(() => {
+        const next = Math.min(2 * ms, WATCH_MAX_MS)
+        if (!closed && watched.size > 0) look(Math.max(next, held - Date.now()))
+        else watch = undefined
+      })
+    }, ms)
+    watch.unref()
+  }
+  const call = (path: string, init: RequestInit = {}): Promise<Response> => {
+    const { GITHUB_API_URL: api, GITHUB_TOKEN: token } = process.env
+    return fetch(`${api}${path}`, {
+      ...init,
+      headers: {
+        ...(init.headers as Record<string, string> | undefined),
+        authorization: `Bearer ${token}`,
+        accept: 'application/vnd.github+json',
+        'content-type': 'application/json',
+        // The version whose dispatch answers with the workflow run's id.
+        'x-github-api-version': '2026-03-10',
+      },
+      signal: AbortSignal.timeout(10_000),
+    })
+  }
+  const dispatch = async (size: string, workers: WorkerSpawn[]): Promise<void> => {
+    const env = process.env
+    const { GITHUB_API_URL: api, GITHUB_REPOSITORY: repo, GITHUB_TOKEN: token } = env
+    if (!api || !repo || !token)
+      throw new Error(
+        'github(): dispatching workers needs GITHUB_TOKEN (actions: write) in a GitHub Actions job',
+      )
+    const sha = env['GITHUB_SHA']
+    const first = workers[0]!
+    // The branch's workflow file, or, once a merged PR's branch is deleted
+    // mid-run (GitHub answers 422 "No ref found"), its base's: the workers
+    // check out `sha` either way.
+    const refs = [env['GITHUB_HEAD_REF'] || env['GITHUB_REF_NAME'], env['GITHUB_BASE_REF']]
+    let res: Response
+    const end = Date.now() + DISPATCH_WAIT_MS
+    for (let i = 0; ;) {
+      res = await call(`/repos/${repo}/actions/workflows/${workflow}/dispatches`, {
+        method: 'POST',
+        body: JSON.stringify({
+          ref: refs[i],
+          inputs: {
+            run: first.run,
+            relay: first.relay,
+            sha,
+            size,
+            workers: JSON.stringify(workers.map((a) => a.id)),
+            // This run's attempt: a worker that starts after it ended
+            // cancels its own workflow run instead of working for no one.
+            ...(env['GITHUB_RUN_ID'] === undefined
+              ? {}
+              : { parent: `${env['GITHUB_RUN_ID']}/attempts/${env['GITHUB_RUN_ATTEMPT'] ?? '1'}` }),
+            ...(options.env === undefined ? {} : { env: handed }),
+          },
+        }),
+      })
+      if (res.ok) break
+      const text = printable((await res.text()).slice(0, 200))
+      const reset = limitReset(res)
+      if (reset !== undefined) {
+        if (reset > end || closed)
+          throw new Error(
+            `github(): dispatching ${workflow}: ${res.status} ${text}${resetsAt(reset)}`,
+          )
+        await Bun.sleep(Math.max(0, reset - Date.now()))
+        continue
+      }
+      if (res.status !== 422 || !text.includes('No ref found') || !refs[++i]) {
+        // GitHub's own words named no fix for the two a first run meets (2026-10-26).
+        const fix =
+          res.status === 404
+            ? `: .github/workflows/${workflow} is not on ${refs[i]} (vx dte init writes it; commit and push it)`
+            : res.status === 403
+              ? ': the job needs `permissions: actions: write` to start workers'
+              : ''
+        throw new Error(`github(): dispatching ${workflow}: ${res.status} ${text}${fix}`)
+      }
+    }
+    const id =
+      res.status === 200
+        ? ((await res.json()) as { workflow_run_id?: number }).workflow_run_id
+        : undefined
+    // An API naming no run (a 204) is refused, not trusted by repository
+    // alone: any job of it with id-token: write would join as a worker.
+    if (id === undefined) {
+      // No run to cancel: each let go meanwhile is settled before the refusal.
+      for (const a of workers) if (cancelled.delete(a.id)) decide(a.id, true)
+      throw new Error(
+        `github(): dispatching ${workflow} named no workflow run (${res.status}): its workers cannot be told from any job of the repository`,
+      )
+    }
+    workerRuns.add(String(id))
+    const run = `/repos/${repo}/actions/runs/${id}`
+    runs.push(run)
+    const mine = new Map(workers.map((a) => [a.id, a]))
+    watched.set(run, mine)
+    if (watch === undefined && !closed) look(WATCH_FIRST_MS)
+    // For the job's last step, which cancels them when this process
+    // dies before close() (a kill, an OOM, the job's timeout).
+    if (env['RUNNER_TEMP']) await appendFile(path.join(env['RUNNER_TEMP'], RUNS_FILE), `${run}\n`)
+    // Let go while this dispatch was in flight: cancel() knew no run.
+    if (!closed) letGo(run, mine)
+  }
+  return {
+    // Loaded only by `vx dte init`: a run never needs it.
+    init: async (setup) => (await import('./init.js')).githubInit(options, setup),
+    keyless: true,
+    workerRuns: () => workerRuns,
+    report(w) {
+      warn = w
+    },
+    adopt(worker) {
+      const temp = process.env['RUNNER_TEMP']
+      if (!temp) return
+      let text: string
+      try {
+        text = readFileSync(path.join(temp, STARTED_FILE), 'utf8')
+        // quiet: no list: this job started no worker
+      } catch {
+        return
+      }
+      for (const line of text.split('\n')) {
+        const [run, ids] = line.trim().split(/\s+/)
+        if (!run || !ids) continue
+        const workers = new Map<string, WorkerSpawn>()
+        for (const id of ids.split(','))
+          workers.set(id, worker(id, id.slice(0, id.lastIndexOf('#'))))
+        runs.push(run)
+        watched.set(run, workers)
+        workerRuns.add(run.slice(run.lastIndexOf('/') + 1))
+      }
+      if (watched.size > 0 && watch === undefined) look(WATCH_FIRST_MS)
+    },
+    spawn(a) {
+      flying.add(a.id)
+      const wave = waves.get(a.size)
+      // A full wave dispatches as it is; the next worker starts another.
+      if (wave !== undefined && wave.length < MATRIX_MAX) {
+        wave.push(a)
+        return
+      }
+      const workers = [a]
+      waves.set(a.size, workers)
+      queueMicrotask(() => {
+        if (waves.get(a.size) === workers) waves.delete(a.size)
+        const p = dispatch(a.size, workers)
+          .catch((err: unknown) => {
+            const why = err instanceof Error ? err.message : String(err)
+            for (const x of workers) {
+              x.exited(why)
+              decide(x.id, false)
+            }
+          })
+          .finally(() => {
+            for (const x of workers) flying.delete(x.id)
+            pending.delete(p)
+          })
+        pending.add(p)
+      })
+    },
+    // Before a worker's setup when its job has yet to run: its runner is
+    // free for others (2026-10-23). A run with a worker still needed, or
+    // a job with a runner, goes on; the workers let go in it are left
+    // running. One given up as late is stopped whatever its job holds.
+    cancel(ids, givenUp) {
+      if (givenUp === true) for (const id of ids) late.add(id)
+      const left = ids.map((id) => new Promise<boolean>((done) => deciding.set(id, done)))
+      // Neither watched nor in flight (its job ended, its dispatch failed): nothing to stop.
+      const gone = ids.filter(
+        (id) => !flying.has(id) && ![...watched.values()].some((w) => w.has(id)),
+      )
+      for (const id of ids) cancelled.add(id)
+      for (const [run, workers] of [...watched])
+        if (ids.some((id) => workers.has(id))) letGo(run, workers)
+      for (const id of gone) decide(id, false)
+      return Promise.all(left).then((l) => ids.filter((_, i) => l[i]))
+    },
+    // A finished run answers 409; one still queued or running is the
+    // run's no more: its results are in, or the run failed without them.
+    async close() {
+      closed = true
+      clearTimeout(watch)
+      await Promise.resolve() // a wave spawned this tick dispatches first
+      await Promise.all(pending)
+      for (const id of [...deciding.keys()]) decide(id, false)
+      // A cancel that fails leaves the run to its timeout, and says so.
+      await Promise.all(runs.splice(0).map(cancelOf))
+    },
+  }
+}
+
+/** The relay token on GitHub Actions: an OIDC token for the relay's URL as audience. */
+export async function githubRelayToken(relay: string): Promise<string | undefined> {
+  const { ACTIONS_ID_TOKEN_REQUEST_URL: url, ACTIONS_ID_TOKEN_REQUEST_TOKEN: bearer } = process.env
+  if (!url || !bearer) return undefined
+  // Loaded when asked: a run that is not distributed loads none of it.
+  const { oidcToken } = await import('./seal.js')
+  return oidcToken(url, bearer, relay).catch((err: unknown) => {
+    throw new UserError(
+      `dte(): ${err instanceof Error ? err.message : String(err)} (for the relay)`,
+    )
+  })
+}
+
+/**
+ * `env` as the workflow's input: each name a variable's, each value one
+ * line, since the workflow writes each as a line of `GITHUB_ENV`. No
+ * secret: a dispatch's inputs are shown with its run, and the worker
+ * job's log prints each step's env unmasked.
+ */
+function handedEnv(env: Readonly<Record<string, string | undefined>>): string {
+  const out: Record<string, string> = {}
+  for (const [name, value] of Object.entries(env)) {
+    if (value === undefined) continue
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || typeof value !== 'string' || /[\r\n]/.test(value))
+      throw new UserError(
+        `github(): env ${JSON.stringify(name)}: a variable's name, and a string of one line`,
+      )
+    if (secretNamed(name))
+      throw new UserError(
+        `github(): env ${JSON.stringify(name)} is a secret, which the worker job's log would show: give it to that job from secrets in its workflow`,
+      )
+    out[name] = value
+  }
+  return JSON.stringify(out)
+}

package/src/gitlab.ts

@@ -0,0 +1,130 @@
+// `gitlab()`: workers as pipelines of the project's own `.gitlab-ci.yml`
+// that the run triggers once it is on the relay (design dte-2026-10.md,
+// "Adapters"): a worker never arrives before its run. The trigger takes
+// the job's `CI_JOB_TOKEN`, so no token is stored. One pipeline per size
+// for each wave the run asks: its `vx-worker <size>` job is a matrix of
+// `max` slots (`VX_DTE_SLOT`), of which the rules run those `VX_DTE_PICK`
+// names, at the run's commit (`VX_DTE_SHA`). Each proves itself by the
+// run's secret.
+
+import { refuseUnknownOptions, type PluginOptionKinds } from '@vzn/vx'
+import type { DteAdapter, WorkerSpawn } from './plugin.js'
+import { printable } from './printable.js'
+
+export interface GitlabOptions {
+  /** Runner tags by worker size: the runners each size's jobs go to. */
+  readonly tags?: Readonly<Record<string, readonly string[]>>
+}
+
+const KEYS: PluginOptionKinds<GitlabOptions> = { tags: 'object' }
+
+export function gitlab(options: GitlabOptions = {}): DteAdapter {
+  refuseUnknownOptions('gitlab()', options, KEYS)
+  // The workers asked in one tick, by size: the run asks a wave at once.
+  const waves = new Map<string, { workers: WorkerSpawn[]; sent: Promise<void> }>()
+  return {
+    init: async (setup) => (await import('./init.js')).gitlabInit(options, setup),
+
+    spawn(a) {
+      let wave = waves.get(a.size)
+      // Two workers in one slot would be one job: the second starts a wave of its own.
+      if (wave === undefined || wave.workers.some((w) => slotOf(w) === slotOf(a))) {
+        const workers: WorkerSpawn[] = []
+        const sent = Promise.resolve().then(() => {
+          if (waves.get(a.size) === mine) waves.delete(a.size)
+          return trigger(workers)
+        })
+        const mine = { workers, sent }
+        wave = mine
+        waves.set(a.size, wave)
+      }
+      wave.workers.push(a)
+      return wave.sent
+    },
+
+    workerId() {
+      const slot = process.env['VX_DTE_SLOT']
+      for (const pair of (process.env['VX_DTE_IDS'] ?? '').split(' ')) {
+        const at = pair.indexOf('=')
+        if (at > 0 && pair.slice(0, at) === slot) return pair.slice(at + 1)
+      }
+      return undefined
+    },
+
+    // Random: a pipeline id is guessable.
+    runId() {
+      return process.env['GITLAB_CI'] === 'true' && process.env['CI_JOB_TOKEN']
+        ? crypto.randomUUID()
+        : undefined
+    },
+  }
+}
+
+/** One pipeline for a wave of one size's workers. */
+async function trigger(workers: readonly WorkerSpawn[]): Promise<void> {
+  const {
+    CI_API_V4_URL: base,
+    CI_PROJECT_ID: project,
+    CI_JOB_TOKEN: token,
+    CI_COMMIT_SHA: sha,
+  } = process.env
+  if (!base || !project || !token || !sha) {
+    const missing = Object.entries({
+      CI_API_V4_URL: base,
+      CI_JOB_TOKEN: token,
+      CI_PROJECT_ID: project,
+      CI_COMMIT_SHA: sha,
+    }).flatMap(([k, v]) => (v ? [] : [k]))
+    throw new Error(`gitlab(): not in a GitLab job (${missing.join(', ')})`)
+  }
+  const first = workers[0]!
+  const slots = workers.map((w) => [slotOf(w), w.id] as const)
+  // A merge request's pipeline is of its source branch; any other, of its
+  // ref. Once a merged request's source branch is deleted mid-run
+  // (GitLab's default), GitLab answers 400 "Reference not found": its
+  // target's file then, as github() does; the workers check out `sha` either way.
+  const refs = [
+    process.env['CI_MERGE_REQUEST_SOURCE_BRANCH_NAME'] || process.env['CI_COMMIT_REF_NAME']!,
+    process.env['CI_MERGE_REQUEST_TARGET_BRANCH_NAME'],
+  ]
+  const { VX_DTE_WORKER: _, ...env } = first.env
+  const vars: Record<string, string> = {
+    ...env,
+    VX_DTE_SIZE: first.size,
+    VX_DTE_SHA: sha,
+    VX_DTE_PICK: `/^(${slots.map(([s]) => s).join('|')})$/`,
+    VX_DTE_IDS: slots.map(([s, id]) => `${s}=${id}`).join(' '),
+  }
+  for (let i = 0; ; i++) {
+    const form = new FormData()
+    form.set('token', token)
+    form.set('ref', refs[i]!)
+    for (const [k, v] of Object.entries(vars)) form.set(`variables[${k}]`, v)
+    const res = await fetch(`${base}/projects/${project}/trigger/pipeline`, {
+      method: 'POST',
+      body: form,
+      signal: AbortSignal.timeout(10_000),
+    })
+    if (res.ok) return
+    const text = printable((await res.text()).slice(0, 200))
+    if (res.status === 400 && text.includes('Reference not found') && refs[i + 1]) continue
+    // GitLab.com's new projects let no one set pipeline variables (17.7),
+    // and GitLab's words name no setting.
+    const fix = text.includes('Insufficient permissions to set pipeline variables')
+      ? ": the workers take the run's variables; in the project's Settings > CI/CD > Variables, let the vx job's role use pipeline variables"
+      : ''
+    throw new Error(
+      `gitlab(): triggering ${workers.map((w) => w.id).join(', ')}: ${res.status} ${text}${fix}`,
+    )
+  }
+}
+
+/**
+ * A worker's matrix slot: its number within its size, wrapped at `max`.
+ * A lost worker's number is never reused, so numbers pass `max`; a wave's
+ * are consecutive and at most `max`, so its slots differ.
+ */
+function slotOf(w: WorkerSpawn): number {
+  const n = Number(w.id.slice(w.id.lastIndexOf('#') + 1))
+  return ((n - 1) % w.max) + 1
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export {
+  dte,
+  type WorkerSize,
+  type WorkerSpawn,
+  type DteAdapter,
+  type DteOptions,
+} from './plugin.js'
+export type { DteInit, DteSetup, PackageManager } from './init.js'
+export { local, type LocalOptions } from './local.js'
+export { docker, type DockerOptions } from './docker.js'
+export { gitlab, type GitlabOptions } from './gitlab.js'
+export { github, type GithubOptions } from './github.js'