@vzn/vx 0.0.16 → 0.0.21

package/src/orchestrator/projects.ts

@@ -0,0 +1,259 @@
+// The project-config load every consumer of "what tasks exist" shares:
+// `prepareRun` (a run, a plan) and `vx show` (introspection). One code
+// path, so what `show` prints is what a run would see — including the
+// plugin `project` stage, which can give tasks to a package that never
+// wrote a `vx.config.ts`.
+
+import type { ProjectConfig } from '../config.js'
+import {
+  frozenProjectConfig,
+  loadProjectConfigs,
+  validateProjectConfig,
+  type LoadProjectConfigOptions,
+  type Lockfile,
+  type PackageGraph,
+  type ProjectEntry,
+  type ProjectMeta,
+} from '../workspace/index.js'
+import type { WorkspaceConfig } from '../config.js'
+import { Cache, noteSchemaReset } from '../cache/index.js'
+import {
+  buildPackageGraph,
+  computeWorkspaceFingerprint,
+  listProjects,
+  loadWorkspace,
+  loadWorkspaceConfig,
+  resolveCacheDir,
+} from '../workspace/index.js'
+import { parseDependencySpec } from '../graph/index.js'
+import { applyConfigHooks, applyProjectHooks, hasHook } from './plugin-host.js'
+import type { VxPlugin } from './plugin.js'
+
+/**
+ * The workspace config with the plugin `config` stage applied — the first
+ * stage of the pipeline, run before anything is derived from the config.
+ * The plugin list itself is already fixed by then.
+ */
+export async function loadWorkspacePlugins(
+  workspaceRoot: string,
+  warn: (message: string) => void,
+): Promise<{ workspaceConfig: WorkspaceConfig | null; plugins: readonly VxPlugin[] }> {
+  const workspaceConfig = await loadWorkspaceConfig(workspaceRoot)
+  const plugins = (workspaceConfig?.plugins ?? []) as readonly VxPlugin[]
+  if (workspaceConfig !== null && hasHook(plugins, 'config')) {
+    await applyConfigHooks(plugins, workspaceConfig, { workspaceRoot, warn })
+  }
+  return { workspaceConfig, plugins }
+}
+
+export interface LoadProjectsArgs {
+  workspaceRoot: string
+  cacheDir: string
+  plugins: readonly VxPlugin[]
+  projectMetas: readonly ProjectMeta[]
+  packageGraph: PackageGraph
+  /**
+   * Projects whose configs must load — `'all'`, or names (unknown and
+   * config-less ones are ignored). With `closure`, each seed's transitive
+   * package dependencies load too, which bounds `^task` frontier
+   * expansion; a `pkg#task` dependsOn entry pulls its project in either
+   * way, since the package graph cannot see the cross form.
+   */
+  seeds: 'all' | Iterable<string>
+  closure: boolean
+  /** Read configs from the lock instead of evaluating them (`--frozen`). */
+  lock: Lockfile | null
+  evalCache: LoadProjectConfigOptions['evalCache']
+  warn: (message: string) => void
+  /**
+   * Entries a load in this same process already produced with the same
+   * cache dir and lock (the CLI's selection pass, which stages every
+   * config to walk `pkg#task` edges). Seeding and scoping run exactly as
+   * without it; a project found here is taken as is instead of being
+   * evaluated and put through the `project` stage a second time — the
+   * stage's cost, and its warnings, once per run. Never carried across
+   * runs: a config can change between them.
+   */
+  staged?: ReadonlyMap<string, ProjectEntry>
+}
+
+export interface LoadedProjects {
+  projects: Map<string, ProjectEntry>
+  /**
+   * Every project that can carry tasks: it has a config file, or a plugin
+   * fills the `project` stage and may give it tasks. Boundary geometry
+   * fences all of them, loaded or not.
+   */
+  configured: readonly ProjectMeta[]
+}
+
+/**
+ * SCOPED config loading: configs are programs, and evaluating 1090 of
+ * them costs ~200 ms — the dominant fixed cost of small runs. Only the
+ * seeds, their closure and any project a `pkg#task` entry names can
+ * contribute graph nodes, so only those configs are evaluated. Side
+ * effect, deliberate and Turbo-like: a broken config in an unrelated
+ * package does not fail a scoped run — it surfaces when that package
+ * enters scope.
+ */
+export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjects> {
+  const { plugins, packageGraph, lock, workspaceRoot } = args
+  // A package with no config file declares no tasks — unless a plugin
+  // fills the `project` stage, in which case it is a project the stage may
+  // give tasks to (the zero-migration shape: `turbo.json` or `package.json`
+  // scripts mapped onto packages that never wrote a `vx.config.ts`). It
+  // then loads as `{ tasks: {} }` — nothing to evaluate, nothing to freeze
+  // — and the stage runs on that like on any loaded config. With no
+  // `project` plugin a plain run never visits (or fences, or seeds) a
+  // config-less package.
+  const projectStage = hasHook(plugins, 'project')
+  const configured = args.projectMetas.filter(
+    (m) => projectStage || (typeof m.configPath === 'string' && m.configPath.length > 0),
+  )
+  const metaByName = new Map<string, ProjectMeta>(configured.map((m) => [m.name, m]))
+  const needed = new Set<string>()
+  const pending: ProjectMeta[] = []
+  const consider = (name: string): void => {
+    if (needed.has(name)) return
+    needed.add(name)
+    const meta = metaByName.get(name)
+    if (meta) pending.push(meta)
+  }
+  const considerWithDeps = (name: string): void => {
+    consider(name)
+    // Every config-bearing project already pending: the closure can add
+    // nothing, and asking for it would build the package graph's
+    // transitive bitsets — a cost the unscoped run (every project a seed)
+    // otherwise never pays.
+    if (pending.length === metaByName.size) return
+    for (const dep of packageGraph.transitiveDeps(name)) consider(dep)
+  }
+  const seeds = args.seeds === 'all' ? metaByName.keys() : [...args.seeds]
+  for (const seed of seeds) consider(seed)
+  if (args.closure && pending.length < metaByName.size) {
+    for (const seed of args.seeds === 'all' ? metaByName.keys() : seeds) considerWithDeps(seed)
+  }
+
+  // Load in rounds to a fixpoint. A `pkg#task` dependsOn entry names a
+  // project the PACKAGE graph cannot reach (the cross form ignores npm
+  // deps by design), so its config has to be pulled in — and that config
+  // may declare cross edges of its own. The common case (no cross deps)
+  // is a single round, identical to loading the closure in one batch.
+  const projects = new Map<string, ProjectEntry>()
+  while (pending.length > 0) {
+    const round = pending.splice(0, pending.length)
+    // Only a config FILE is evaluated (or read from the lock); a
+    // config-less project in the round starts from an empty task table,
+    // and a project the caller already staged is neither.
+    const withFile = round.filter(
+      (m): m is ProjectMeta & { configPath: string } =>
+        typeof m.configPath === 'string' && args.staged?.get(m.name) === undefined,
+    )
+    const loaded = lock
+      ? await Promise.all(withFile.map((m) => frozenProjectConfig(lock, m, workspaceRoot)))
+      : await loadProjectConfigs(
+          withFile.map((m) => m.configPath),
+          args.evalCache !== undefined ? { evalCache: args.evalCache } : {},
+        )
+    let next = 0
+    for (const meta of round) {
+      const pre = args.staged?.get(meta.name)
+      if (pre !== undefined) {
+        projects.set(meta.name, pre)
+        for (const name of crossDepProjects(pre.config)) {
+          if (args.closure) considerWithDeps(name)
+          else consider(name)
+        }
+        continue
+      }
+      const config: ProjectConfig =
+        meta.configPath === null ? { tasks: {} } : (loaded[next++] as ProjectConfig)
+      if (projectStage) {
+        // The `project` stage edits the validated object in place; core
+        // re-validates after EACH plugin so a plugin can only produce what
+        // the loader accepts from a user, and the refusal names both the
+        // config file and the plugin whose edit broke it.
+        const where = meta.configPath ?? `${meta.name} (no config file)`
+        await applyProjectHooks(
+          plugins,
+          config,
+          {
+            workspaceRoot,
+            cacheDir: args.cacheDir,
+            warn: args.warn,
+            name: meta.name,
+            dir: meta.dir,
+            packageJson: meta.packageJson as unknown as Readonly<Record<string, unknown>>,
+            projects: args.projectMetas,
+          },
+          (plugin) => validateProjectConfig(config, `${where} (after plugin '${plugin.name}')`),
+        )
+      }
+      projects.set(meta.name, { name: meta.name, dir: meta.dir, config })
+      for (const name of crossDepProjects(config)) {
+        if (args.closure) considerWithDeps(name)
+        else consider(name)
+      }
+    }
+  }
+  return { projects, configured }
+}
+
+/** Project names named by a `pkg#task` dependsOn entry anywhere in `config`. */
+function crossDepProjects(config: ProjectConfig): string[] {
+  const out: string[] = []
+  for (const task of Object.values(config.tasks ?? {})) {
+    for (const raw of task.dependsOn ?? []) {
+      // A malformed spec is the graph builder's error to report — it names
+      // the offending task. Here it just contributes no project.
+      if (!raw.includes('#')) continue
+      try {
+        const spec = parseDependencySpec(raw)
+        if (spec.kind === 'cross') out.push(spec.project)
+      } catch {
+        continue
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * The run path's view of a workspace's projects for a reader — `vx show`,
+ * the MCP server, an embedder: discovery, the plugin `config` and
+ * `project` stages, and the local cache opened only to serve cached
+ * evaluations, so a pure config costs a stat, not an evaluation. `scope`
+ * is every project or a list of names; no closure, no lock (a reader
+ * reads live, as a default run does). Plugin warnings go to `warn`.
+ */
+export async function loadResolvedProjects(
+  workspaceRoot: string,
+  opts: { scope?: 'all' | readonly string[]; warn?: (message: string) => void } = {},
+): Promise<Map<string, ProjectEntry>> {
+  const warn = opts.warn ?? ((): void => {})
+  const metas = await listProjects(await loadWorkspace(workspaceRoot))
+  const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, warn)
+  const cacheDir = resolveCacheDir(workspaceRoot, workspaceConfig)
+  const cache = new Cache(cacheDir)
+  noteSchemaReset(cache, warn)
+  try {
+    const loaded = await loadProjects({
+      workspaceRoot,
+      cacheDir,
+      plugins,
+      projectMetas: metas,
+      packageGraph: buildPackageGraph([...metas]),
+      seeds: opts.scope ?? 'all',
+      closure: false,
+      lock: null,
+      evalCache: {
+        store: cache,
+        workspaceFingerprint: await computeWorkspaceFingerprint(workspaceRoot),
+      },
+      warn,
+    })
+    return loaded.projects
+  } finally {
+    cache.close()
+  }
+}

package/src/orchestrator/remote-prefetch.ts

@@ -14,17 +14,20 @@
 // HARD SCOPE: this runs ONLY when a remote layer is configured. It
 // NEVER touches the local cache (no local get / no isOutputsCurrent /
 // no stat pass) — it derives keys and probes REMOTE only. Local-only
-// runs are byte-identical to before; the caller gates on `cache
-// instanceof LayeredCache`.
+// runs are byte-identical to before; the caller gates on the layer's
+// own `hasRemote`, so a third-party remote layer gets the overlap too.
+// The two batch-probe hooks are OPTIONAL on the contract: a remote layer
+// that implements neither still prefetches, per-hash.
 
 import type { TaskNode } from '../graph/index.js'
-import type { GitFilesCache, LayeredCache } from '../cache/index.js'
+import type { CacheLayer, GitFilesCache } from '../cache/index.js'
 import type { HashCache } from './task-hash.js'
 import { deriveStableKeys } from './stable-keys.js'
 
 export interface PrefetchArgs {
   nodes: Map<string, TaskNode>
-  cache: LayeredCache
+  /** A layer whose `hasRemote` is true — the caller's gate. */
+  cache: CacheLayer
   workspaceRoot: string
   workspaceFingerprint: string
   forwardArgs?: readonly string[] | undefined
@@ -67,13 +70,14 @@ async function runPrefetch(args: PrefetchArgs): Promise<void> {
   // tells us which of the N stable hashes exist remotely, so we GET only the
   // hits and pre-mark the misses — their lazy `get` then short-circuits with
   // no network. This collapses N probe waves into 1 and skips every GET that
-  // would 404. When the remote can't batch (`null` — an older serve, or reads
-  // disabled), fall back to prefetching every stable key, exactly as before.
+  // would 404. When the remote can't batch (`null` — an older remote, reads
+  // disabled, or a layer that doesn't implement the hook at all), fall back to
+  // prefetching every stable key, exactly as before.
   let toPrefetch = stableKeys
   const uniqueHashes = [...new Set(stableKeys.map((k) => k.hash))]
-  const present = await args.cache.remoteHasMany(uniqueHashes)
+  const present = (await args.cache.remoteHasMany?.(uniqueHashes)) ?? null
   if (present !== null) {
-    args.cache.markRemoteAbsent(uniqueHashes.filter((h) => !present.has(h)))
+    args.cache.markRemoteAbsent?.(uniqueHashes.filter((h) => !present.has(h)))
     toPrefetch = stableKeys.filter((k) => present.has(k.hash))
     if (toPrefetch.length === 0) return
   }

package/src/orchestrator/run-artifacts.ts

@@ -14,8 +14,9 @@
 // Both are no-ops if the corresponding RunOptions field is undefined.
 
 import path from 'node:path'
-import type { TaskOutcome } from '../graph/index.js'
+import { isGroupTask, type TaskOutcome } from '../graph/index.js'
 import { tallyOutcomes } from './tally.js'
+import type { FlakyFinding } from './failure-mode.js'
 
 export interface SummarizeArgs {
   /** Empty string → default path; otherwise the explicit file path. */
@@ -26,7 +27,48 @@ export interface SummarizeArgs {
   startedAtMs: number
   endedAtMs: number
   totalMs: number
+  /** The run's verdict — the same value the CLI turns into the exit code. */
+  ok: boolean
   outcomes: readonly TaskOutcome[]
+  /** What `detectFlaky` found this run; the footer's Flaky section, typed. */
+  flaky?: readonly FlakyFinding[]
+}
+
+/** One task's entry. Shared by `tasks` and `aborted` so they read alike. */
+function taskEntry(o: TaskOutcome, flaky?: FlakyFinding): Record<string, unknown> {
+  return {
+    id: o.node.id,
+    project: o.node.projectName,
+    task: o.node.taskName,
+    status: o.status,
+    exitCode: o.exitCode,
+    durationMs: o.durationMs,
+    hash: o.hash ?? null,
+    // A task with no `cache` block executes every run by design; without
+    // the flag a consumer computing a hit rate cannot tell a miss from a
+    // task that could never hit (its `hash` is still set — dependents fold
+    // it). Present only when true, so every other row is byte-identical.
+    ...(o.node.config.cache === undefined ? { noCache: true } : {}),
+    // Present only when the run proved the task flaky: this exact key has
+    // both passed and failed on record (this run counted), or the task
+    // needed a retry. A consumer gating on `failed` can tell a break from a
+    // flake without the history; every other row is byte-identical.
+    ...(flaky !== undefined
+      ? { flaky: { passes: flaky.passes, failures: flaky.failures, attempts: flaky.attempts } }
+      : {}),
+    ...(o.cpuMs !== undefined ? { cpuMs: o.cpuMs } : {}),
+    ...(o.peakRssBytes !== undefined ? { peakRssBytes: o.peakRssBytes } : {}),
+    // A hit's row names what the PRODUCING execution used under its own
+    // keys, so a consumer never reads a remote worker's peak as this run's.
+    ...(o.storedCpuMs !== undefined ? { storedCpuMs: o.storedCpuMs } : {}),
+    ...(o.storedPeakRssBytes !== undefined ? { storedPeakRssBytes: o.storedPeakRssBytes } : {}),
+    // Present only when an `admit` policy held the task with a worker free.
+    ...(o.admissionHeldMs !== undefined ? { admissionHeldMs: o.admissionHeldMs } : {}),
+    // hrtime spans are bigints → emit as strings so JSON.parse on
+    // the consumer side doesn't truncate the ns precision.
+    ...(o.wallclockStartNs !== undefined ? { wallclockStartNs: String(o.wallclockStartNs) } : {}),
+    ...(o.wallclockEndNs !== undefined ? { wallclockEndNs: String(o.wallclockEndNs) } : {}),
+  }
 }
 
 export async function writeRunSummary(args: SummarizeArgs): Promise<string> {
@@ -34,26 +76,31 @@ export async function writeRunSummary(args: SummarizeArgs): Promise<string> {
     args.target === ''
       ? path.join(args.cacheDir, 'runs', `${args.runId}.json`)
       : path.resolve(args.cwd, args.target)
+  // `tasks` and `summary` must describe the same population, or one artifact
+  // contradicts itself (a group task listed in `tasks` but absent from
+  // `summary.total`). `tallyOutcomes` owns the rule; mirror its filter here.
+  const counted = args.outcomes.filter((o) => !isGroupTask(o.node) && o.status !== 'aborted')
+  // A task killed by a shutdown signal is in no bucket and no total, yet it
+  // makes the run red. Listing it separately keeps `tasks.length ===
+  // summary.total` while leaving the artifact able to explain a non-zero
+  // exit — the terminal has said so in its Aborted section all along, and a
+  // parser must not be told less than a human is.
+  const aborted = args.outcomes.filter((o) => !isGroupTask(o.node) && o.status === 'aborted')
+  const flakyById = new Map((args.flaky ?? []).map((f) => [f.taskId, f]))
   const payload = {
     runId: args.runId,
+    // The run-level verdict, first: a consumer gating on this artifact must
+    // not have to re-derive it by re-implementing the bucket rules.
+    ok: args.ok,
+    exitCode: args.ok ? 0 : 1,
     startedAt: new Date(args.startedAtMs).toISOString(),
     endedAt: new Date(args.endedAtMs).toISOString(),
     totalMs: args.totalMs,
-    tasks: args.outcomes.map((o) => ({
-      id: o.node.id,
-      project: o.node.projectName,
-      task: o.node.taskName,
-      status: o.status,
-      exitCode: o.exitCode,
-      durationMs: o.durationMs,
-      hash: o.hash ?? null,
-      ...(o.cpuMs !== undefined ? { cpuMs: o.cpuMs } : {}),
-      ...(o.peakRssBytes !== undefined ? { peakRssBytes: o.peakRssBytes } : {}),
-      // hrtime spans are bigints → emit as strings so JSON.parse on
-      // the consumer side doesn't truncate the ns precision.
-      ...(o.wallclockStartNs !== undefined ? { wallclockStartNs: String(o.wallclockStartNs) } : {}),
-      ...(o.wallclockEndNs !== undefined ? { wallclockEndNs: String(o.wallclockEndNs) } : {}),
-    })),
+    tasks: counted.map((o) => taskEntry(o, flakyById.get(o.node.id))),
+    aborted: aborted.map((o) => taskEntry(o)),
+    // The FULL list: `tallyOutcomes` applies the same group/aborted
+    // exclusions internally, so every counted bucket is unchanged by passing
+    // it — but `summary.aborted` is only non-zero if it sees them.
     summary: tallyOutcomes(args.outcomes),
   }
   await Bun.write(outPath, JSON.stringify(payload, null, 2))

package/src/orchestrator/run-context.ts

@@ -3,6 +3,10 @@
 // probes are best-effort — a missing git binary, a non-repo cwd, or an
 // unset env degrades each field to null and NEVER throws. Telemetry must
 // not be able to fail a build.
+//
+// Cost: ONE git spawn (`captureGitContext`) on every run, plus two more
+// (`captureWorkspaceIdentity`, `captureDefaultBranch`) only when a plugin
+// declares the `telemetry` capability — nobody else needs those fields.
 
 import fs from 'node:fs'
 import os from 'node:os'
@@ -42,9 +46,23 @@ export interface HostContext {
  * `dirty: null` when unavailable. Each field degrades to null
  * independently — telemetry never fails a run.
  */
-export function captureGitContext(workspaceRoot: string, dirty: boolean | null = null): GitContext {
+export function captureGitContext(
+  workspaceRoot: string,
+  dirty: boolean | null = null,
+  env: NodeJS.ProcessEnv | Record<string, string | undefined> = process.env,
+): GitContext {
   let commitSha: string | null = null
   let branch: string | null = null
+  // Read `.git` directly first: HEAD plus one ref file (or packed-refs) is
+  // ~0.1 ms, where the spawn below is ~8 ms — on EVERY run, including a
+  // 60 ms warm one. The spawn stays as the fallback for whatever the reader
+  // does not understand (a ref format this code has not seen, a gitdir it
+  // cannot resolve), so an unusual repo is slower, never wrong.
+  const direct = readHeadDirect(workspaceRoot)
+  if (direct !== null) {
+    branch = direct.branch ?? ciBranch(env)
+    return { commitSha: direct.commitSha, branch, dirty }
+  }
   try {
     const proc = Bun.spawnSync({
       cmd: ['git', '-C', workspaceRoot, 'rev-parse', 'HEAD', '--abbrev-ref', 'HEAD'],
@@ -56,14 +74,154 @@ export function captureGitContext(workspaceRoot: string, dirty: boolean | null =
       const sha = lines[0]?.trim()
       const br = lines[1]?.trim()
       if (sha) commitSha = sha
-      if (br) branch = br
+      // `--abbrev-ref HEAD` answers the literal string `HEAD` when nothing is
+      // checked out. Recording that verbatim INVENTS a branch: every detached
+      // run shares a pseudo-branch "HEAD", which is how `actions/checkout`
+      // leaves a pull_request build. The trust boundary (`branch ===
+      // defaultBranch`) means it is at least never mistaken for trunk, but
+      // every PR collapses into one scope — so one PR's timings feed another's
+      // baseline, cross-branch regression detection counts them as a single
+      // branch, and a consumer grouping runs by branch reads "HEAD".
+      if (br && br !== 'HEAD') branch = br
     }
   } catch {
     // git unavailable / non-repo: both fields stay null.
   }
+  // A detached CI checkout still knows the branch it came from; the provider
+  // says so even though git cannot. Same most-reliable-first ladder as
+  // `captureDefaultBranch`, and consulted only when git had no answer — an
+  // attached branch is ground truth for what this working tree IS, so a stale
+  // exported variable must never relabel it.
+  branch ??= ciBranch(env)
   return { commitSha, branch, dirty }
 }
 
+/**
+ * `HEAD`'s commit and branch from the `.git` files, or null when anything
+ * about the layout is unfamiliar (the caller then spawns git). Handles a
+ * `.git` directory, a `.git` FILE (`gitdir: …` — a linked worktree, whose
+ * refs live under `commondir`), a symbolic HEAD, a detached HEAD, loose refs
+ * and `packed-refs`.
+ */
+function readHeadDirect(
+  workspaceRoot: string,
+): { commitSha: string; branch: string | null } | null {
+  try {
+    let gitDir = path.join(workspaceRoot, '.git')
+    const st = fs.statSync(gitDir)
+    if (st.isFile()) {
+      const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(gitDir, 'utf8'))
+      if (m === null) return null
+      gitDir = path.resolve(workspaceRoot, m[1]!.trim())
+    }
+    let commonDir = gitDir
+    const commonFile = path.join(gitDir, 'commondir')
+    if (fs.existsSync(commonFile)) {
+      commonDir = path.resolve(gitDir, fs.readFileSync(commonFile, 'utf8').trim())
+    }
+    const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim()
+    const SHA = /^[0-9a-f]{40,64}$/
+    if (SHA.test(head)) return { commitSha: head, branch: null }
+    const ref = /^ref:\s*(refs\/heads\/(.+))$/.exec(head)
+    if (ref === null) return null
+    const refPath = ref[1]!
+    const branch = ref[2]!
+    for (const base of [gitDir, commonDir]) {
+      const loose = path.join(base, refPath)
+      if (fs.existsSync(loose)) {
+        const sha = fs.readFileSync(loose, 'utf8').trim()
+        return SHA.test(sha) ? { commitSha: sha, branch } : null
+      }
+    }
+    const packed = path.join(commonDir, 'packed-refs')
+    if (fs.existsSync(packed)) {
+      for (const line of fs.readFileSync(packed, 'utf8').split('\n')) {
+        if (line.endsWith(` ${refPath}`)) {
+          const sha = line.slice(0, line.length - refPath.length - 1)
+          return SHA.test(sha) ? { commitSha: sha, branch } : null
+        }
+      }
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The branch a CI provider says this checkout came from, or null.
+ *
+ * On a GitHub pull_request `GITHUB_REF_NAME` is `<n>/merge` — the merge ref,
+ * not a branch anyone works on — so `GITHUB_HEAD_REF` (the contributor's
+ * actual branch, set only for pull_request events) has to win.
+ */
+function ciBranch(env: NodeJS.ProcessEnv | Record<string, string | undefined>): string | null {
+  for (const key of ['GITHUB_HEAD_REF', 'GITHUB_REF_NAME', 'CI_COMMIT_REF_NAME']) {
+    const v = env[key]
+    if (typeof v === 'string' && v.trim().length > 0) return v.trim()
+  }
+  return null
+}
+
+/**
+ * The repository's DEFAULT (trunk) branch — the axis that separates a
+ * mainline run from a PR / feature-branch experiment. A run whose `branch`
+ * equals this is a trunk run; everything else is branch work whose timings
+ * must NOT pollute the shared scheduling baseline (owner 2026-07-14: "I can
+ * be experimenting on a branch increasing task time for all later on… don't
+ * count their times into main"). Resolution ladder, most-reliable first:
+ *   1. GitLab: `CI_DEFAULT_BRANCH` (the project's configured default).
+ *   2. GitHub Actions: the event payload's `repository.default_branch`
+ *      (present on push AND pull_request events) — one best-effort JSON read.
+ *   3. Local / other: `git symbolic-ref --short refs/remotes/origin/HEAD`,
+ *      stripping the `origin/` prefix.
+ * Returns null when none resolve (a detached checkout with no remote HEAD, a
+ * non-repo cwd) — the consumer then counts ALL runs, so an undetectable
+ * default never regresses today's behavior. Never throws.
+ */
+export function captureDefaultBranch(
+  env: NodeJS.ProcessEnv | Record<string, string | undefined>,
+  workspaceRoot: string,
+): string | null {
+  const gitlab = env['CI_DEFAULT_BRANCH']
+  if (typeof gitlab === 'string' && gitlab.trim().length > 0) return gitlab.trim()
+
+  const eventPath = env['GITHUB_EVENT_PATH']
+  if (typeof eventPath === 'string' && eventPath.length > 0) {
+    try {
+      // Only a regular file. A character device (`/dev/zero`) never reaches
+      // EOF, so readFileSync would spin forever — "never throws" is not the
+      // same as "never hangs", and a run must not wedge on a stray env var.
+      if (!fs.statSync(eventPath).isFile()) throw new Error('not a regular file')
+      const payload = JSON.parse(fs.readFileSync(eventPath, 'utf8')) as {
+        repository?: { default_branch?: unknown }
+      }
+      const dflt = payload.repository?.default_branch
+      if (typeof dflt === 'string' && dflt.trim().length > 0) return dflt.trim()
+    } catch {
+      // unreadable / malformed payload — fall through to git.
+    }
+  }
+
+  try {
+    const proc = Bun.spawnSync({
+      cmd: ['git', '-C', workspaceRoot, 'symbolic-ref', '--short', 'refs/remotes/origin/HEAD'],
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    if (proc.exitCode === 0) {
+      const ref = new TextDecoder().decode(proc.stdout).trim()
+      // `refs/remotes/origin/HEAD` → `origin/main`; strip the remote prefix.
+      const slash = ref.indexOf('/')
+      const name = slash >= 0 ? ref.slice(slash + 1) : ref
+      if (name.length > 0) return name
+    }
+  } catch {
+    // git unavailable / no remote HEAD ref: null.
+  }
+  return null
+}
+
 // Recognized CI env vars in match-priority order. The first whose value
 // is truthy (present and not '0'/'false') decides the provider; a bare
 // `CI` is the generic fallback.
@@ -91,32 +249,6 @@ export function detectCi(env: NodeJS.ProcessEnv | Record<string, string | undefi
   return { ci: false, provider: null }
 }
 
-/**
- * The untrusted per-PR cache partition — a stable identity for THIS pull
- * request, so one fork PR's untrusted cache writes are isolated from another's
- * (no cross-PR pollution or leakage). `VX_CACHE_SCOPE` overrides; otherwise
- * derived from the CI PR context (GitHub PR number, GitLab MR iid, else the
- * head branch). Returns undefined outside a PR (the serve then falls back to a
- * shared untrusted scope). Never throws — sanitized to one safe path segment.
- */
-export function resolveCacheScope(
-  env: NodeJS.ProcessEnv | Record<string, string | undefined>,
-): string | undefined {
-  const safe = (s: string): string => s.replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 128)
-  const override = env['VX_CACHE_SCOPE']
-  if (isTruthy(override)) return safe(override as string)
-  // GitHub: a pull_request run has GITHUB_REF = refs/pull/<n>/merge.
-  const ref = env['GITHUB_REF']
-  const m = typeof ref === 'string' ? /^refs\/pull\/(\d+)\//.exec(ref) : null
-  if (m) return `pr-${m[1]}`
-  const headRef = env['GITHUB_HEAD_REF']
-  if (isTruthy(headRef)) return `gh-${safe(headRef as string)}`
-  // GitLab merge request.
-  const iid = env['CI_MERGE_REQUEST_IID']
-  if (isTruthy(iid)) return `mr-${safe(iid as string)}`
-  return undefined
-}
-
 /** Host name (null on failure) + platform + arch. */
 export function captureHostContext(): HostContext {
   let host: string | null = null
@@ -144,9 +276,15 @@ export interface WorkspaceIdentity {
  */
 export function normalizeRemoteUrl(raw: string): string {
   let s = raw.trim().toLowerCase()
+  const hadProtocol = /^[a-z+]+:\/\//.test(s)
   s = s.replace(/^[a-z+]+:\/\//, '') // protocol
   s = s.replace(/^[^@/]+@/, '') // user[:pass]@
-  s = s.replace(/:(\d+\/)/, '/$1') // :port/ → /
+  // A `:port` only appears in a protocol-form URL (`ssh://host:2222/path`); the
+  // scp shorthand `host:path` has no port. STRIP it (the old code reinserted it
+  // as a path segment, so `ssh://host:2222/o/r` and `https://host/o/r` — the
+  // SAME repo — derived different workspace ids). Gated on `hadProtocol` so a
+  // scp path whose first segment is numeric isn't mistaken for a port.
+  if (hadProtocol) s = s.replace(/:\d+(\/|$)/, '$1')
   s = s.replace(/:/, '/') // scp-style host:path
   s = s.replace(/\.git$/, '').replace(/\/+$/, '')
   return s