@vzn/vx-ci 0.0.646 → 0.0.648

package/README.md

@@ -24,12 +24,23 @@ export default defineWorkspace({
 That's the whole setup. On a GitHub Actions runner (`GITHUB_STEP_SUMMARY`
 set) every `vx run` appends a summary block, on its own line after
 anything already written in the step: verdict headline, stats
-(tasks / executed / cache hits / duration), failures called out above the
-per-task table with their exit code, the signal an exit above 128
+(tasks / executed / cache hits / duration, and the ideal time an executor says
+the run could have taken, as `@vzn/vx-dte` replays it), failures called out above the
+per-task table (rows by status, failures first, then the longest first) with their exit code, the signal an exit above 128
 stands for (`exit 137 (128 + SIGKILL)`, as the run's own frame and
 `vx last` say it), a timeout as `timed out, exit 143`, a persistent task
 that never became ready as `never ready (timed out)`, a sandboxed task's
-violation count, and the tasks each failure blocked. A footer line
+violation count, and the tasks each failure blocked. A server a
+DTE run carried to its dependants' workers reads `served`,
+with no duration of its own. When an executor
+ran the run on other machines (`@vzn/vx-dte`'s workers), a Workers table
+shows each one's status, when it was asked for, its total time (warm-up
+plus online), its warm-up, its time online after the warm-up and the part
+of that with no task on it (a task counts from its send to its result,
+restore and save included), its tasks, the cores
+its tasks were expected to use (their last run's) beside the cores it used, its peak RAM of its memory, and
+its utilization, under a line
+of the expected and used share of all their core-time (the expected share over the workers whose executor reports one). Tasks the executor left to the run's own machine get a `this machine` row, and a line splits the executed count between workers and this machine. A footer line
 names the vx version, the command (what follows `--` counted, not
 quoted), tasks passed and outputs restored.
 Anywhere else (`GITHUB_ACTIONS` not `true`: laptops, other CI)
@@ -41,15 +52,12 @@ checked and nothing loads, so declaring it unconditionally is safe.
 The options type is `GithubPluginOptions`; `renderJobSummary` renders the
 summary lines the plugin posts (the site's CI guide sample is rendered from it).
 The package exports `github`, `gitlab`, `renderJobSummary` and the types
-`GithubPluginOptions`, `GitlabPluginOptions` and `FetchFn`; nothing else. `fetchFn`, `append` and `sizeOf` are test seams:
-they replace the Checks API transport, the summary writer and its size probe.
+`GithubPluginOptions` and `GitlabPluginOptions`; nothing else.
 
 ```ts
 github({
   summaryFile: '/path/override.md', // default: $GITHUB_STEP_SUMMARY
   title: 'build & test', // default: 'vx run'
-  checks: true, // default: on with GITHUB_TOKEN; true warns when it is missing, false opts out
-  checkName: 'ci', // default: 'vx', the check run's name
   cacheScope: false, // default: on; scope plugin cache entries by ref
 })
 ```
@@ -59,20 +67,32 @@ github({
 On Actions (`GITHUB_ACTIONS=true`) the plugin's `config` stage names the
 run's branch through `ctx.setBranch`, from the ref (`GITHUB_REF`,
 `GITHUB_REF_NAME`, `GITHUB_HEAD_REF`, `GITHUB_REPOSITORY`) and the
-`GITHUB_EVENT_PATH` payload. A push to the default branch names no scope.
+`GITHUB_EVENT_PATH` payload. A push to the default branch (the
+workspace's `baseBranch`, else the event's) names no scope.
 A push to, or a pull request from, a branch names
 `<owner>/<repo>:<branch>` of the repository the branch lives in, so a
 fork's pull request names the fork; so does a `pull_request_target` or
 `workflow_run` run on a PR's behalf (by `GITHUB_EVENT_NAME`, though its
 ref is main's), and an `issue_comment` on a PR, which names no branch,
-`pr-<n>`. A merge queue's run (`merge_group`) is trusted: no scope,
-whatever its `gh-readonly-queue/...` branch, compared with
+`pr-<n>`. A merge queue's run (`merge_group`) is trusted, whatever its
+`gh-readonly-queue/...` branch: no scope, compared with
 `merge_group.base_sha`. A pull request also names its base commit
 (`pull_request.base.sha`), the base of a bare `--affected`. The scope
 keys only what plugins store themselves (`ctx.cache`, run records):
 task keys never carry it, and the cache server decides from the CI OIDC
 token where a task's entry lands. `VX_CACHE_SCOPE` overrides it.
 
+It also names the refs a remote cache reads, in order (`refs`): a pull
+request's merge ref (`refs/pull/<n>/merge`, the one scope its token
+writes), then the run's own branch (a pull request's head, a
+`workflow_run` a pull request started included, else `GITHUB_REF`), then
+the branch it merges into (`GITHUB_BASE_REF`, or that `workflow_run`'s
+pull request's base), then the default branch (the
+workspace's `baseBranch`, else the event's). A merge queue's run reads
+only its base branch (`merge_group.base_ref`, else the queue ref's
+`<base>`): it is about to become that branch, and the server writes its
+entries there.
+
 ## GitLab CI
 
 ```ts
@@ -95,50 +115,82 @@ fork's `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`) and its diff base
 (`CI_MERGE_REQUEST_DIFF_BASE_SHA`), the base of a bare `--affected`.
 A merge train's pipeline (`CI_MERGE_REQUEST_EVENT_TYPE=merge_train`)
 builds what lands on the target, so it is trusted: no scope. As on
-Actions, the scope keys only plugin entries. `gitlab({ cacheScope: false })` (`GitlabPluginOptions`) turns it off;
+Actions, the scope keys only plugin entries. A remote reads the tag, else
+the merge request's source branch, else `CI_COMMIT_REF_NAME`, then the
+target (`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`, an external pull
+request's `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME`), then the default branch
+(`baseBranch`, else `CI_DEFAULT_BRANCH`); a merge train reads only its
+target. `gitlab({ cacheScope: false })` (`GitlabPluginOptions`) turns it off;
 `VX_CACHE_SCOPE` overrides it. Anywhere else `gitlab()` returns
 `undefined`, so declaring both plugins is safe. Merge request comments
 and reports are not part of it yet.
 
-## How it works
+## The sandbox runtime: `vx setup`
 
-`github()` contributes one observe-only telemetry sink through vx's
-`telemetry` seam. It receives the versioned `RunSummaryRecord` at run end
-and renders + appends the markdown in `flush()` — it holds no run handle,
-streams no per-event records (`wants: []`), and a slow or failing write can
-never fail or stall the run (core's crash-isolation + flush deadline).
+A task that declares `exec.sandbox` needs the OS sandbox on the machine
+that runs it. On Linux that is bubblewrap, socat, strace and ripgrep,
+with bwrap allowed its user namespaces. One step before vx runs sets it
+up:
 
-## The PR check run
+```yaml
+# GitHub Actions
+- run: vx setup github
+```
 
-With `GITHUB_TOKEN` in the environment (plus `GITHUB_REPOSITORY` /
-`GITHUB_SHA`, both set by the runner) the plugin also creates one
-**completed check-run** on the built commit — conclusion `success`,
-`failure`, or `cancelled` for a run a signal stopped with nothing
-failed (a cancelled job), its output the same summary markdown — so the verdict shows in
-the PR's checks list, not just the workflow page. The workflow must grant
-the permission:
+```yaml
+# GitLab CI
+script:
+  - vx setup gitlab
+```
+
+It installs what is missing (apt-get by sudo, or apk), lets bwrap make
+user namespaces where AppArmor restricts them (Ubuntu 24+; Ubuntu 26's
+`bwrap-userns-restrict` profile is replaced, as it strips the namespace
+the sandbox nests), and proves bwrap starts a sandbox, failing the step
+if it cannot. On macOS the sandbox is built in and it does nothing.
+
+The packages it fetched stay in a directory the job's cache can keep:
+`~/.cache/vx/setup-debs` on Actions, `.vx-setup-debs` under
+`CI_PROJECT_DIR` on GitLab, or `--debs <dir>`. When that directory holds them, they install
+with no index fetch; when they do not install (an older image's) or
+leave a tool missing (one that image had already), they are fetched
+again. The directory holds a `*` `.gitignore`, so no task's inputs
+read it (on GitLab it sits in the checkout). On Actions the step's outputs, written to
+`GITHUB_OUTPUT`, are `fetched` and `key`
+(`vx-setup-debs-<RUNNER_OS>-<RUNNER_ARCH>-<image>-<version>`, the
+runner image's, which the restore prefix below finds), so a cache step
+saves only what it fetched. Save only from the default branch's own
+runs: the restored debs install as root with `dpkg -i`, which checks no
+signature, and a restore takes the newest key of the prefix, so a
+pull request's code saving there would reach every later job:
 
 ```yaml
-permissions:
-  checks: write
+- uses: actions/cache/restore@v5
+  with:
+    path: ~/.cache/vx/setup-debs
+    key: vx-setup-debs-${{ runner.os }}-${{ runner.arch }}
+    restore-keys: vx-setup-debs-${{ runner.os }}-${{ runner.arch }}-
+- id: setup
+  run: vx setup github
+- if: steps.setup.outputs.fetched == 'true' && github.ref == 'refs/heads/main'
+  uses: actions/cache/save@v5
+  with:
+    path: ~/.cache/vx/setup-debs
+    key: ${{ steps.setup.outputs.key }}
 ```
 
-Without the token the check is silently skipped (the job summary still
-writes); pass `checks: true` to warn instead, or `checks: false` to opt
-out entirely; a value that is not a boolean is refused. GitHub's own blips (`502`, `503`, `504`, a dropped
-connection) are retried twice, 200 then 800 ms apart, until the flush deadline, which warns the last answer. A failed POST warns and never fails the run — a `403` says
-to check `permissions: checks: write`, a rate limit (`429`, or a `403`
-saying so) says so and is not retried — and a slow API costs the run
-nothing past core's end-of-run flush deadline. On `pull_request` events
-`GITHUB_SHA` is the merge commit; GitHub still surfaces the check on the
-PR.
-
-On GitHub Enterprise Server the POST goes to `GITHUB_API_URL`. A host
-behind a private CA is trusted through `NODE_EXTRA_CA_CERTS` (a PEM
-file of the CA); an untrusted certificate is not retried and its warning
-names that variable.
-
-Both artifacts are bounded by GitHub's own limits, because exceeding
-either loses the whole thing rather than its tail: the check-run output
-at 65 535 bytes, the job summary at 1 MiB counted in bytes (about 19 000 task rows; fewer when task names are not ASCII), cut on a character boundary. GitHub's cap is the step's whole summary file, so the page fits in what earlier writers in the step left; with no room it is skipped with a warning.
-Past either, what is written ends with a line saying it was truncated.
+The verb is the plugin's: `vx setup github` exists where `github()` is
+declared and the job is on Actions, `vx setup gitlab` where `gitlab()` is
+and the job is on GitLab CI. Core has no `setup` verb.
+
+## How it works
+
+`github()` contributes one observe-only telemetry sink through vx's
+`telemetry` hook. It receives the versioned `RunSummaryRecord` at run end
+and renders + appends the markdown in `flush()` — it holds no run handle,
+streams no per-event records (`wants: []`), and a slow or failing write can
+never fail or stall the run (core's crash-isolation + flush deadline).
+
+The job summary is bounded by GitHub's own limit, because exceeding it
+loses the whole page rather than its tail: 1 MiB counted in bytes (about 19 000 task rows; fewer when task names are not ASCII), cut on a character boundary. GitHub's cap is the step's whole summary file, so the page fits in what earlier writers in the step left; with no room it is skipped with a warning.
+Past it, what is written ends with a line saying it was truncated.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-ci",
-  "version": "0.0.646",
+  "version": "0.0.648",
   "license": "MIT",
   "description": "GitHub Actions and GitLab CI integration for vx — a job summary on Actions and the branch cache scope on both.",
   "keywords": [
@@ -9,8 +9,7 @@
     "monorepo",
     "github-actions",
     "gitlab-ci",
-    "job-summary",
-    "checks"
+    "job-summary"
   ],
   "type": "module",
   "main": "./src/index.ts",
@@ -28,13 +27,13 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4"
+    "bun": ">=1.4.4"
   },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.646"
+    "@vzn/vx": "^0.0.648"
   },
   "repository": {
     "type": "git",

package/src/cache-scope.ts

@@ -1,11 +1,11 @@
 // The cache scope and base commit a GitHub Actions run names through
 // `setBranch`: none on the default branch, a branch its own scope, the one
-// a laptop on that branch derives (owner, 2026-10-17).
+// a laptop on that branch derives (2026-10-17).
 import { readFile } from 'node:fs/promises'
 import { type BranchFacts, branchCacheScope } from '@vzn/vx'
 
 /**
- * What an Actions run knows of its branch (owner, 2026-10-17). `scope`:
+ * What an Actions run knows of its branch (2026-10-17). `scope`:
  * none on a push to the default branch, outside Actions, or when the ref
  * is unknown; else `<owner>/<repo>:<branch>`, the repository and branch a
  * pull request comes from, or the branch or tag pushed. A fork's pull
@@ -15,18 +15,73 @@ import { type BranchFacts, branchCacheScope } from '@vzn/vx'
  * `workflow_run` a PR started) is the PR's, whatever `GITHUB_REF` says: a
  * workflow that checks out the PR's head there would otherwise share main's
  * scope. `issue_comment` names no branch, so it writes `pr-<n>`.
- * A merge queue's run (`merge_group`) is trusted (owner, 2026-10-18): no
- * scope, compared with `merge_group.base_sha`.
+ * A merge queue's run (`merge_group`) is trusted (2026-10-18): no
+ * scope, compared with `merge_group.base_sha`. A push to a branch named
+ * like a queue ref is not one: anyone who can push can name one.
  * `base`: a pull request's base commit (`pull_request.base.sha`), what its
- * merge checkout is compared with, no git call needed.
+ * merge checkout is compared with, no git call needed. `refs`: what a
+ * remote reads (`githubRefs`).
  */
 export async function githubBranch(
   env: Readonly<Record<string, string | undefined>>,
+  baseBranch?: string,
 ): Promise<BranchFacts> {
   if (env['GITHUB_ACTIONS'] !== 'true') return {}
-  const ref = env['GITHUB_REF'] ?? ''
   const event = await eventOf(env['GITHUB_EVENT_PATH'])
-  if (env['GITHUB_EVENT_NAME'] === 'merge_group') {
+  const refs = githubRefs(env, event, baseBranch)
+  const facts = scopeOf(env, event, baseBranch)
+  return refs.length === 0 ? facts : { ...facts, refs }
+}
+
+/** The queue ref GitHub names a merge queue's run: `refs/heads/gh-readonly-queue/<base>/pr-<n>-<sha>`. */
+const QUEUE = /^refs\/heads\/gh-readonly-queue\/(.+)\/pr-\d+-(?:[0-9a-f]{40}|[0-9a-f]{64})$/
+
+/**
+ * The refs an Actions run reads, in order (2026-10-25): a merge
+ * queue's run only its base branch, the code it is about to become; any
+ * other a pull request's merge ref (`refs/pull/<n>/merge`, the one scope
+ * its token writes), then its own branch (a pull request's head, a
+ * `workflow_run` a pull request started included, else `GITHUB_REF`), then
+ * the branch it merges into, then the default branch (`baseBranch`, else
+ * the event's).
+ */
+function githubRefs(
+  env: Readonly<Record<string, string | undefined>>,
+  event: ActionsEvent | undefined,
+  baseBranch: string | undefined,
+): string[] {
+  const head = (b: string | undefined) => (b === undefined ? undefined : `refs/heads/${b}`)
+  const ref = stringOf(env['GITHUB_REF'])
+  if (queued(env)) {
+    const base = stringOf(event?.merge_group?.base_ref) ?? head(QUEUE.exec(ref ?? '')?.[1])
+    return base === undefined ? [] : [base]
+  }
+  const merge = /^refs\/pull\/\d+\//.test(ref ?? '') ? ref : undefined
+  // A workflow_run a pull request started is the PR's, as its scope is.
+  const run = prRun(env['GITHUB_EVENT_NAME'], event)
+  const own = head(stringOf(env['GITHUB_HEAD_REF']) ?? stringOf(run?.head_branch)) ?? ref
+  const into = head(
+    stringOf(env['GITHUB_BASE_REF']) ?? stringOf(run?.pull_requests?.[0]?.base?.ref),
+  )
+  const trunk = head(baseBranch ?? stringOf(event?.repository?.default_branch))
+  return [...new Set([merge, own, into, trunk].filter((r): r is string => r !== undefined))]
+}
+
+/**
+ * A merge queue's run: a `merge_group` event only. Anyone who can push can
+ * name a branch like a queue ref, so the cache server renames only a
+ * `merge_group` run's ref to its base, and only it reads just that base.
+ */
+const queued = (env: Readonly<Record<string, string | undefined>>): boolean =>
+  env['GITHUB_EVENT_NAME'] === 'merge_group'
+
+function scopeOf(
+  env: Readonly<Record<string, string | undefined>>,
+  event: ActionsEvent | undefined,
+  baseBranch: string | undefined,
+): BranchFacts {
+  const ref = env['GITHUB_REF'] ?? ''
+  if (queued(env)) {
     const base = stringOf(event?.merge_group?.base_sha)
     return { trusted: true, ...(base !== undefined ? { base } : {}) }
   }
@@ -47,8 +102,10 @@ export async function githubBranch(
   if (onBehalf !== undefined) return withBase(onBehalf)
   const name = env['GITHUB_REF_NAME']
   if (ref === '' || name === undefined || name === '' || repo === undefined) return {}
-  const branch = event?.repository?.default_branch
-  if (typeof branch === 'string' && branch !== '' && ref === `refs/heads/${branch}`) return {}
+  // The workspace's `baseBranch` first, as the refs read it: a run on it
+  // has no scope even where the event names no default branch.
+  const branch = baseBranch ?? stringOf(event?.repository?.default_branch)
+  if (branch !== undefined && ref === `refs/heads/${branch}`) return {}
   return { scope: branchCacheScope(repo, name) }
 }
 
@@ -60,12 +117,12 @@ interface ActionsEvent {
     base?: { sha?: unknown }
   }
   issue?: { number?: unknown; pull_request?: unknown }
-  merge_group?: { base_sha?: unknown }
+  merge_group?: { base_sha?: unknown; base_ref?: unknown }
   workflow_run?: {
     event?: unknown
     head_branch?: unknown
     head_repository?: { full_name?: unknown }
-    pull_requests?: { number?: unknown }[]
+    pull_requests?: { number?: unknown; base?: { ref?: unknown } }[]
   }
 }
 
@@ -95,12 +152,8 @@ function prOf(
     const n = event.issue.number
     return typeof n === 'number' && Number.isInteger(n) && n > 0 ? `pr-${n}` : 'pr-target'
   }
-  const run = event?.workflow_run
-  if (
-    name === 'workflow_run' &&
-    typeof run?.event === 'string' &&
-    run.event.startsWith('pull_request')
-  ) {
+  const run = prRun(name, event)
+  if (run !== undefined) {
     const branch = stringOf(run.head_branch)
     return branch === undefined
       ? 'pr-target'
@@ -109,6 +162,19 @@ function prOf(
   return undefined
 }
 
+/** A `workflow_run` run's triggering run, when a pull request started it. */
+function prRun(
+  name: string | undefined,
+  event: ActionsEvent | undefined,
+): NonNullable<ActionsEvent['workflow_run']> | undefined {
+  const run = event?.workflow_run
+  return name === 'workflow_run' &&
+    typeof run?.event === 'string' &&
+    run.event.startsWith('pull_request')
+    ? run
+    : undefined
+}
+
 /** The event payload the runner writes; undefined when it cannot be read. */
 async function eventOf(eventPath: string | undefined): Promise<ActionsEvent | undefined> {
   if (eventPath === undefined || eventPath === '') return undefined

package/src/gitlab.ts

@@ -1,15 +1,9 @@
-// The `gitlab()` plugin (owner, 2026-10-18): on GitLab CI it names the
+// The `gitlab()` plugin (2026-10-18): on GitLab CI it names the
 // run's branch through `setBranch`, as `github()` does on Actions. Off
 // GitLab CI (`GITLAB_CI` not 'true') the factory returns undefined, which
 // `plugins` skips, so declaring it costs nothing on a laptop.
-import {
-  type BranchFacts,
-  branchCacheScope,
-  definePlugin,
-  type PluginOptionKinds,
-  refuseUnknownOptions,
-  type VxPlugin,
-} from '@vzn/vx'
+import { type BranchFacts, branchCacheScope, definePlugin, type VxPlugin } from '@vzn/vx'
+import path from 'node:path'
 
 export interface GitlabPluginOptions {
   /**
@@ -22,17 +16,24 @@ export interface GitlabPluginOptions {
   cacheScope?: boolean
 }
 
-const GITLAB_PLUGIN_KEYS: PluginOptionKinds<GitlabPluginOptions> = {
-  cacheScope: 'boolean',
-}
-
 export function gitlab(options: GitlabPluginOptions = {}): VxPlugin | undefined {
   if (process.env['GITLAB_CI'] !== 'true') return undefined
-  refuseUnknownOptions('gitlab()', options, GITLAB_PLUGIN_KEYS)
   return definePlugin(import.meta, {
-    config(_workspace, ctx) {
+    commands: {
+      // In the project: GitLab's `cache: paths` keeps only what is under it.
+      setup: {
+        description: 'gitlab: install and prove the sandbox runtime on this job',
+        run: async (argv) =>
+          (await import('./setup.js')).runSetup(
+            'gitlab',
+            argv,
+            path.join(process.env['CI_PROJECT_DIR'] ?? process.cwd(), '.vx-setup-debs'),
+          ),
+      },
+    },
+    config(workspace, ctx) {
       if (options.cacheScope === false) return
-      ctx.setBranch(gitlabBranch(process.env))
+      ctx.setBranch(gitlabBranch(process.env, workspace.baseBranch))
     },
   })
 }
@@ -43,9 +44,43 @@ export function gitlab(options: GitlabPluginOptions = {}): VxPlugin | undefined
  * `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`) and its diff base; a merge
  * train's pipeline builds what lands on the target, so it is trusted; a
  * branch or tag pipeline names its ref, none on the default branch.
+ * `refs`, what a remote reads (2026-10-25): a merge train's only its
+ * target branch; any other its own ref (the tag, else a merge request's
+ * source branch, else the branch), then
+ * a merge request's or external pull request's target, then the default
+ * branch.
  */
-function gitlabBranch(env: Readonly<Record<string, string | undefined>>): BranchFacts {
+function gitlabBranch(
+  env: Readonly<Record<string, string | undefined>>,
+  baseBranch?: string,
+): BranchFacts {
   const value = (key: string): string | undefined => env[key] || undefined
+  const head = (b: string | undefined) => (b === undefined ? undefined : `refs/heads/${b}`)
+  const tag = value('CI_COMMIT_TAG')
+  const target = head(
+    value('CI_MERGE_REQUEST_TARGET_BRANCH_NAME') ??
+      value('CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME'),
+  )
+  const train = value('CI_MERGE_REQUEST_EVENT_TYPE') === 'merge_train'
+  const refs = [
+    ...new Set(
+      (train
+        ? [target]
+        : [
+            tag !== undefined
+              ? `refs/tags/${tag}`
+              : head(value('CI_MERGE_REQUEST_SOURCE_BRANCH_NAME') ?? value('CI_COMMIT_REF_NAME')),
+            target,
+            head(baseBranch ?? value('CI_DEFAULT_BRANCH')),
+          ]
+      ).filter((r): r is string => r !== undefined),
+    ),
+  ]
+  const facts = scopeOf(value)
+  return refs.length === 0 ? facts : { ...facts, refs }
+}
+
+function scopeOf(value: (key: string) => string | undefined): BranchFacts {
   const base = value('CI_MERGE_REQUEST_DIFF_BASE_SHA')
   const withBase = (facts: BranchFacts): BranchFacts =>
     base === undefined ? facts : { ...facts, base }

package/src/index.ts

@@ -9,7 +9,13 @@
 // appends a job summary: verdict, stats, failures, and the per-task table.
 // Anywhere else the plugin declines and costs nothing.
 import { createRequire } from 'node:module'
-import type { RunSummaryRecord, VxPlugin } from '@vzn/vx'
+import {
+  type PluginOptionKinds,
+  refuseUnknownOptions,
+  type RunSummaryRecord,
+  UserError,
+  type VxPlugin,
+} from '@vzn/vx'
 import type { GithubPluginOptions } from './plugin.js'
 import type { GitlabPluginOptions } from './gitlab.js'
 
@@ -21,12 +27,33 @@ export type { GithubPluginOptions, GitlabPluginOptions }
 // factories are synchronous.
 const load = createRequire(import.meta.url)
 
-export function github(options?: GithubPluginOptions): VxPlugin | undefined {
+// Options are checked here, on CI or not: a typo checked only on CI passed
+// on a laptop and failed the first CI run (2026-10-28).
+const GITHUB_KEYS: PluginOptionKinds<GithubPluginOptions> = {
+  summaryFile: 'string',
+  title: 'string',
+  cacheScope: 'boolean',
+}
+
+const GITLAB_KEYS: PluginOptionKinds<GitlabPluginOptions> = {
+  cacheScope: 'boolean',
+}
+
+export function github(options: GithubPluginOptions = {}): VxPlugin | undefined {
+  refuseUnknownOptions('github()', options, GITHUB_KEYS)
+  // '' passes the kind check but reads wrong: `??` keeps it, so summaryFile
+  // declined instead of using GITHUB_STEP_SUMMARY and title rendered an
+  // empty heading.
+  for (const key of ['summaryFile', 'title'] as const) {
+    if (options[key] === '')
+      throw new UserError(`github() option "${key}" must be a non-empty string, got ""`)
+  }
   if (process.env['GITHUB_ACTIONS'] !== 'true') return undefined
   return (load('./plugin.js') as typeof import('./plugin.js')).github(options)
 }
 
-export function gitlab(options?: GitlabPluginOptions): VxPlugin | undefined {
+export function gitlab(options: GitlabPluginOptions = {}): VxPlugin | undefined {
+  refuseUnknownOptions('gitlab()', options, GITLAB_KEYS)
   if (process.env['GITLAB_CI'] !== 'true') return undefined
   return (load('./gitlab.js') as typeof import('./gitlab.js')).gitlab(options)
 }
@@ -34,7 +61,3 @@ export function gitlab(options?: GitlabPluginOptions): VxPlugin | undefined {
 export function renderJobSummary(summary: RunSummaryRecord, title?: string): string {
   return (load('./summary.js') as typeof import('./summary.js')).renderJobSummary(summary, title)
 }
-
-// The Checks API helpers are the plugin's own; only the transport type
-// the options name is public (1.0 freezes what this file exports).
-export { type FetchFn } from './checks.js'