@vzn/vx 0.0.0 → 0.0.12

package/src/orchestrator/protocol.ts

@@ -0,0 +1,142 @@
+// The client↔service wire contract. A `vx run` client submits a
+// `RunRequest`; the service streams `WireEvent`s and returns a
+// `RunResult`. Transport-agnostic by design — the same messages travel a
+// local unix/ws hop today or a hosted `wss://` link tomorrow. Pure types +
+// the RunOptions⇄RunRequest mapping; no transport, no execution here.
+
+import type { CachePolicy } from '../cache/index.js'
+import type { ContinueMode } from '../graph/index.js'
+import type { OutcomeView, WireEvent } from './events.js'
+import type { RunOptions } from './options.js'
+
+/**
+ * The serializable subset of `RunOptions` a client sends to the service.
+ * Omits the non-serializable / host-side fields (`log`, `bus`,
+ * `handleSignals`) — those are the service's concern.
+ */
+export interface RunRequest {
+  tasks: readonly string[]
+  cwd: string
+  projects?: readonly string[]
+  concurrency?: number
+  cache?: CachePolicy
+  /** `--cache-dir <path>` override (cwd-relative). */
+  cacheDir?: string
+  continueMode?: ContinueMode
+  frozen?: boolean
+  /** Run-level retry default (`--retry <n>`); explicit `exec.retries` wins. */
+  retries?: number
+  /** Run-level task-timeout default (ms); per-task `exec.timeout` wins. */
+  timeout?: number
+  /** Cache-correctness verification (`--verify`); `allow` as an array (Sets
+   *  don't serialize). */
+  verify?: { determinism: boolean; inputs: boolean; allow: readonly string[] }
+  flow?: 'focused' | 'broad'
+  outputLogs?: 'full' | 'errors-only' | 'none'
+  excludeDependencies?: 'all' | readonly string[]
+  forwardArgs?: readonly string[]
+  summarize?: string
+  profile?: string
+  /** Free-form key/value labels from `--tag`, persisted on the invocation row. */
+  tags?: Record<string, string>
+  /** The raw `vx run …` command string, recorded on the invocation row. */
+  command?: string
+}
+
+export interface RunResult {
+  ok: boolean
+  outcomes: OutcomeView[]
+}
+
+/**
+ * Where a `vx run` executes. The client submits a serializable
+ * `RunRequest` and gets back a `RunResult`; it neither knows nor cares
+ * whether the work happened in-process or was delegated to a service.
+ * This is the currency of the `backend` plugin capability — part of the
+ * public wire contract (it lives here, not in `cli`, so a plugin can
+ * reference it without a `cli` import).
+ */
+export interface RunBackend {
+  run(request: RunRequest): Promise<RunResult>
+}
+
+/**
+ * service → client. The submitter contract: an event stream, a final
+ * result, or an error. The distributed-execution variants
+ * (`task:assign`/`agent:refused`/`coord:drain`) live in a distribution
+ * plugin's protocol module — its WS handler unions this with those.
+ */
+export type ServerMessage =
+  | { t: 'event'; event: WireEvent }
+  | { t: 'result'; result: RunResult }
+  | { t: 'error'; message: string }
+
+/**
+ * client → service. The submitter contract: a run submission. The
+ * agent-side `agent:*` family lives in a distribution plugin's protocol
+ * module.
+ */
+export type ClientMessage = { t: 'run'; request: RunRequest }
+
+/** Project resolved `RunOptions` down to the serializable request. */
+export function optionsToRequest(options: RunOptions): RunRequest {
+  const req: RunRequest = { tasks: options.tasks, cwd: options.cwd }
+  if (options.projects !== undefined) req.projects = options.projects
+  if (options.concurrency !== undefined) req.concurrency = options.concurrency
+  if (options.cache !== undefined) req.cache = options.cache
+  if (options.cacheDir !== undefined) req.cacheDir = options.cacheDir
+  if (options.continueMode !== undefined) req.continueMode = options.continueMode
+  if (options.frozen !== undefined) req.frozen = options.frozen
+  if (options.retries !== undefined) req.retries = options.retries
+  if (options.timeout !== undefined) req.timeout = options.timeout
+  if (options.verify !== undefined)
+    req.verify = {
+      determinism: options.verify.determinism,
+      inputs: options.verify.inputs,
+      allow: [...options.verify.allow],
+    }
+  if (options.flow !== undefined) req.flow = options.flow
+  if (options.outputLogs !== undefined) req.outputLogs = options.outputLogs
+  if (options.excludeDependencies !== undefined)
+    req.excludeDependencies = options.excludeDependencies
+  if (options.forwardArgs !== undefined) req.forwardArgs = options.forwardArgs
+  if (options.summarize !== undefined) req.summarize = options.summarize
+  if (options.profile !== undefined) req.profile = options.profile
+  if (options.tags !== undefined) req.tags = options.tags
+  if (options.command !== undefined) req.command = options.command
+  return req
+}
+
+/**
+ * Rebuild `RunOptions` from a request, for the side that actually executes
+ * (the local backend, or the service). The caller adds the host-side
+ * fields it needs (`bus`, `log`, `handleSignals`).
+ */
+export function requestToOptions(request: RunRequest): RunOptions {
+  const options: RunOptions = { cwd: request.cwd, tasks: [...request.tasks] }
+  if (request.projects !== undefined) options.projects = [...request.projects]
+  if (request.concurrency !== undefined) options.concurrency = request.concurrency
+  if (request.cache !== undefined) options.cache = request.cache
+  if (request.cacheDir !== undefined) options.cacheDir = request.cacheDir
+  if (request.continueMode !== undefined) options.continueMode = request.continueMode
+  if (request.frozen !== undefined) options.frozen = request.frozen
+  if (request.retries !== undefined) options.retries = request.retries
+  if (request.timeout !== undefined) options.timeout = request.timeout
+  if (request.verify !== undefined)
+    options.verify = {
+      determinism: request.verify.determinism,
+      inputs: request.verify.inputs,
+      allow: new Set(request.verify.allow),
+    }
+  if (request.flow !== undefined) options.flow = request.flow
+  if (request.outputLogs !== undefined) options.outputLogs = request.outputLogs
+  if (request.excludeDependencies !== undefined) {
+    options.excludeDependencies = request.excludeDependencies
+  }
+  if (request.forwardArgs !== undefined) options.forwardArgs = request.forwardArgs
+  if (request.summarize !== undefined) options.summarize = request.summarize
+  if (request.profile !== undefined) options.profile = request.profile
+  if (request.tags !== undefined) options.tags = request.tags
+  if (request.command !== undefined) options.command = request.command
+  return options
+}

package/src/orchestrator/remote-cache-setup.ts

@@ -0,0 +1,60 @@
+import {
+  Cache,
+  type CacheLayer,
+  type CachePolicy,
+  FULL_CACHE_POLICY,
+  LayeredCache,
+  RemoteCache,
+} from '../cache/index.js'
+import type { Logger } from './logger.js'
+import { resolveCacheScope } from './run-context.js'
+
+/**
+ * Wrap the local cache in a `LayeredCache` when a remote cache is configured
+ * via `VX_REMOTE_CACHE_URL` + a token. This is the escape hatch for a
+ * THIRD-PARTY, Turbo-compatible cache server. A `cache` plugin can provide a
+ * remote cache INTERNALLY instead, in which case this env path isn't
+ * needed.
+ *
+ * **Trust tier follows the token you present** — the server derives
+ * trusted/untrusted from the bearer, so the client just presents whichever
+ * token it has: `VX_REMOTE_CACHE_TOKEN` for a trusted context, or
+ * `VX_REMOTE_CACHE_PR_TOKEN` for a fork PR (reads the trusted cache, writes
+ * only the untrusted scope). A fork-PR CI job simply doesn't hold the trusted
+ * secret, so "which token you have" IS the tier — no separate trust flag.
+ *
+ * Optional env: `VX_REMOTE_CACHE_TEAM_ID`, `VX_REMOTE_CACHE_SLUG`
+ * (Turbo tenancy query params), `VX_REMOTE_CACHE_TIMEOUT_MS`,
+ * `VX_REMOTE_CACHE_SIGNATURE_KEY` (HMAC artifact signing).
+ */
+export function wrapWithRemoteCache(
+  local: Cache,
+  log: Logger,
+  policy: CachePolicy = FULL_CACHE_POLICY,
+): CacheLayer {
+  const url = process.env.VX_REMOTE_CACHE_URL
+  const token = process.env.VX_REMOTE_CACHE_TOKEN ?? process.env.VX_REMOTE_CACHE_PR_TOKEN
+  if (!url || !token) return local
+
+  const config: ConstructorParameters<typeof RemoteCache>[0] = { baseUrl: url, token }
+  const teamId = process.env.VX_REMOTE_CACHE_TEAM_ID
+  if (teamId) config.teamId = teamId
+  const slug = process.env.VX_REMOTE_CACHE_SLUG
+  if (slug) config.slug = slug
+  const timeoutMs = process.env.VX_REMOTE_CACHE_TIMEOUT_MS
+  if (timeoutMs) {
+    const n = Number(timeoutMs)
+    if (Number.isFinite(n) && n > 0) config.timeoutMs = n
+  }
+  const signatureKey = process.env.VX_REMOTE_CACHE_SIGNATURE_KEY
+  if (signatureKey) config.signatureKey = signatureKey
+  // Untrusted per-PR isolation: a fork PR's writes land in its own sub-scope.
+  const cacheScope = resolveCacheScope(process.env)
+  if (cacheScope) config.cacheScope = cacheScope
+
+  log.status(`remote cache: ${url}`)
+  return new LayeredCache(local, new RemoteCache(config), {
+    onRemoteError: (err) => log.status(`[vx] remote cache: ${err.message}`),
+    policy,
+  })
+}

package/src/orchestrator/remote-prefetch.ts

@@ -0,0 +1,81 @@
+// Remote-cache prefetch (remote-only). When a run is backed by a
+// LayeredCache, the network latency of every remote cache GET would
+// otherwise sit on the critical path of the task that needs it. This
+// module derives every cacheable task's pure-input key UP FRONT
+// (reusing the run's hashCache memo, so execute-task's later
+// computeTaskHash for the same task hits the memo — no double hashing)
+// and fires the remote GETs concurrently, in the background, before
+// execution starts. LayeredCache.prefetch ingests each hit into the
+// LOCAL cache and de-dups against the lazy read-through, so when
+// execute-task calls cache.get it transparently awaits the already
+// in-flight (resolved-or-pending) remote promise — at most ONE remote
+// GET per key.
+//
+// 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`.
+
+import type { TaskNode } from '../graph/index.js'
+import type { GitFilesCache, LayeredCache } 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
+  workspaceRoot: string
+  workspaceFingerprint: string
+  forwardArgs?: readonly string[] | undefined
+  nestedDirsByProject: Map<string, string[]>
+  gitFilesCache: GitFilesCache
+  hashCache: HashCache
+  /** Cap on concurrent in-flight prefetches — the run's concurrency. */
+  concurrency: number
+  /** When false (remote reads disabled), no prefetch fires. */
+  remoteRead: boolean
+}
+
+/**
+ * Fire remote prefetches for every STABLE cached task in the graph.
+ * Fire-and-forget from the caller's perspective: this kicks off an
+ * async derivation + bounded prefetch pool and returns immediately so
+ * execution starts concurrently. A remote-read-off policy short-circuits.
+ *
+ * Stability gate: see `deriveStableKeys` — a task's key is "stable"
+ * only if its inputs can't be altered by an upstream task's outputs.
+ * Unstable tasks fall back to lazy read-through in execute-task, which
+ * is always correct.
+ */
+export function startRemotePrefetch(args: PrefetchArgs): Promise<void> {
+  if (!args.remoteRead) return Promise.resolve()
+  // Detached from EXECUTION: the caller does NOT await this before
+  // scheduling, so prefetch network latency overlaps the run. But the
+  // caller DOES await the returned handle before closing the cache, so
+  // a still-in-flight prefetch can never ingest into a closed DB. Errors
+  // degrade inside LayeredCache.prefetch; the catch keeps the handle
+  // from ever rejecting.
+  return runPrefetch(args).catch(() => {})
+}
+
+async function runPrefetch(args: PrefetchArgs): Promise<void> {
+  const stableKeys = await deriveStableKeys(args)
+  if (stableKeys.length === 0) return
+
+  // Bounded worker pool over the stable keys. Each prefetch is
+  // self-contained (LayeredCache owns the in-flight map + ingest); we
+  // cap concurrency so a 1000-task run doesn't open 1000 sockets at
+  // once. The pumps race alongside execution.
+  let next = 0
+  const workers = Math.max(1, Math.min(args.concurrency, stableKeys.length))
+  const pump = async (): Promise<void> => {
+    while (next < stableKeys.length) {
+      const { hash, node } = stableKeys[next++]!
+      await args.cache
+        .prefetch(hash, { taskId: node.id, command: node.config.exec?.command ?? '' })
+        .catch(() => false)
+    }
+  }
+  await Promise.all(Array.from({ length: workers }, () => pump()))
+}

package/src/orchestrator/run-artifacts.ts

@@ -0,0 +1,111 @@
+// Optional per-run output artifacts:
+//
+//   --summarize[=<path>] → JSON describing every task's outcome
+//                          (id, status, exit code, durations, hash,
+//                          cpu_ms, peak_rss_bytes, hrtime spans).
+//                          Default path: <cacheDir>/runs/<run_id>.json.
+//
+//   --profile[=<path>]   → Chrome-trace JSON of the run. Each task is
+//                          a single complete event (`ph: 'X'`) with
+//                          ts / dur in microseconds derived from the
+//                          hrtime spans the runner already captures.
+//                          Default path: profile.json (cwd-relative).
+//
+// Both are no-ops if the corresponding RunOptions field is undefined.
+
+import path from 'node:path'
+import type { TaskOutcome } from '../graph/index.js'
+import { tallyOutcomes } from './tally.js'
+
+export interface SummarizeArgs {
+  /** Empty string → default path; otherwise the explicit file path. */
+  target: string
+  cacheDir: string
+  cwd: string
+  runId: string
+  startedAtMs: number
+  endedAtMs: number
+  totalMs: number
+  outcomes: readonly TaskOutcome[]
+}
+
+export async function writeRunSummary(args: SummarizeArgs): Promise<string> {
+  const outPath =
+    args.target === ''
+      ? path.join(args.cacheDir, 'runs', `${args.runId}.json`)
+      : path.resolve(args.cwd, args.target)
+  const payload = {
+    runId: args.runId,
+    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) } : {}),
+    })),
+    summary: tallyOutcomes(args.outcomes),
+  }
+  await Bun.write(outPath, JSON.stringify(payload, null, 2))
+  return outPath
+}
+
+export interface ProfileArgs {
+  target: string
+  cwd: string
+  outcomes: readonly TaskOutcome[]
+}
+
+/**
+ * Chrome trace JSON. Spec:
+ *   https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU
+ *
+ * One complete event (`ph: 'X'`) per task with `ts` and `dur` in
+ * microseconds (Chrome's unit; we have ns from hrtime, divide by 1000).
+ * Each project gets its own `tid` so concurrent tasks render on
+ * distinct rows in chrome://tracing or perfetto.
+ */
+export async function writeRunProfile(args: ProfileArgs): Promise<string> {
+  const outPath = path.resolve(args.cwd, args.target)
+  const tidByProject = new Map<string, number>()
+  const traceEvents = args.outcomes
+    .filter((o) => o.wallclockStartNs !== undefined && o.wallclockEndNs !== undefined)
+    .map((o) => {
+      let tid = tidByProject.get(o.node.projectName)
+      if (tid === undefined) {
+        tid = tidByProject.size + 1
+        tidByProject.set(o.node.projectName, tid)
+      }
+      // ns → us; bigint arithmetic to avoid precision loss before
+      // converting to a JSON-safe number.
+      const startUs = Number((o.wallclockStartNs ?? 0n) / 1000n)
+      const durUs = Number(((o.wallclockEndNs ?? 0n) - (o.wallclockStartNs ?? 0n)) / 1000n)
+      return {
+        name: o.node.id,
+        cat: o.status,
+        ph: 'X',
+        ts: startUs,
+        dur: durUs,
+        pid: 1,
+        tid,
+        args: {
+          exitCode: o.exitCode,
+          hash: o.hash ?? null,
+          ...(o.cpuMs !== undefined ? { cpuMs: o.cpuMs } : {}),
+          ...(o.peakRssBytes !== undefined ? { peakRssBytes: o.peakRssBytes } : {}),
+        },
+      }
+    })
+  await Bun.write(outPath, JSON.stringify({ traceEvents }, null, 2))
+  return outPath
+}

package/src/orchestrator/run-context.ts

@@ -0,0 +1,205 @@
+// Per-run context capture for the Tier-3 `invocations` header row:
+// git (commit / branch / dirty), CI provider, and host/os/arch. All
+// 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.
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { ulid, xxh3hex } from '../util/index.js'
+
+export interface GitContext {
+  /** `git rev-parse HEAD`, or null outside a repo / on failure. */
+  commitSha: string | null
+  /** `git rev-parse --abbrev-ref HEAD`, or null. */
+  branch: string | null
+  /** True if `git status --porcelain` was non-empty; null on failure. */
+  dirty: boolean | null
+}
+
+export interface CiContext {
+  ci: boolean
+  /** Which CI matched: 'github' | 'gitlab' | 'buildkite' | 'circleci'
+   *  | 'generic' (bare `CI`), or null when no CI env is present. */
+  provider: string | null
+}
+
+export interface HostContext {
+  host: string | null
+  os: string
+  arch: string
+}
+
+/**
+ * One short `git` spawn per run (not per task), behind try/catch.
+ * `git rev-parse HEAD --abbrev-ref HEAD` returns the commit on line 1
+ * and the branch on line 2 in a SINGLE invocation — half the spawns of
+ * two separate `rev-parse` calls. `dirty` is NOT probed here: the run's
+ * `GitFilesCache` populate already ran `git status --porcelain` for
+ * input enumeration, so the orchestrator passes that aggregate in
+ * (`dirty`) rather than paying for a second status spawn. Pass
+ * `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 {
+  let commitSha: string | null = null
+  let branch: string | null = null
+  try {
+    const proc = Bun.spawnSync({
+      cmd: ['git', '-C', workspaceRoot, 'rev-parse', 'HEAD', '--abbrev-ref', 'HEAD'],
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    if (proc.exitCode === 0) {
+      const lines = new TextDecoder().decode(proc.stdout).trim().split('\n')
+      const sha = lines[0]?.trim()
+      const br = lines[1]?.trim()
+      if (sha) commitSha = sha
+      if (br) branch = br
+    }
+  } catch {
+    // git unavailable / non-repo: both fields stay null.
+  }
+  return { commitSha, branch, dirty }
+}
+
+// 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.
+const CI_PROVIDERS: ReadonlyArray<[envVar: string, provider: string]> = [
+  ['GITHUB_ACTIONS', 'github'],
+  ['GITLAB_CI', 'gitlab'],
+  ['BUILDKITE', 'buildkite'],
+  ['CIRCLECI', 'circleci'],
+  ['CI', 'generic'],
+]
+
+function isTruthy(v: string | undefined): boolean {
+  return v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false'
+}
+
+/**
+ * Detect a CI environment + which provider. `ci=true` if any recognized
+ * var is truthy; `provider` names the most-specific match (a specific
+ * provider beats the generic `CI`).
+ */
+export function detectCi(env: NodeJS.ProcessEnv | Record<string, string | undefined>): CiContext {
+  for (const [varName, provider] of CI_PROVIDERS) {
+    if (isTruthy(env[varName])) return { ci: true, provider }
+  }
+  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
+  try {
+    const h = os.hostname()
+    host = h.length > 0 ? h : null
+  } catch {
+    host = null
+  }
+  return { host, os: process.platform, arch: process.arch }
+}
+
+export interface WorkspaceIdentity {
+  /** Stable 16-hex id — same for every checkout of the same repo. */
+  id: string
+  /** Human name for switchers/badges: the repo (or root dir) basename. */
+  name: string
+}
+
+/**
+ * Normalize a git remote URL so every checkout of the same repository
+ * derives the SAME workspace id: `git@github.com:o/r.git`,
+ * `ssh://git@github.com/o/r`, and `https://github.com/o/r.git` all
+ * reduce to `github.com/o/r`.
+ */
+export function normalizeRemoteUrl(raw: string): string {
+  let s = raw.trim().toLowerCase()
+  s = s.replace(/^[a-z+]+:\/\//, '') // protocol
+  s = s.replace(/^[^@/]+@/, '') // user[:pass]@
+  s = s.replace(/:(\d+\/)/, '/$1') // :port/ → /
+  s = s.replace(/:/, '/') // scp-style host:path
+  s = s.replace(/\.git$/, '').replace(/\/+$/, '')
+  return s
+}
+
+/**
+ * Stable workspace identity for the multi-workspace server story
+ * (telemetry schema v2). Derivation ladder:
+ *   1. git remote origin URL, normalized → xxh3 (same id from any
+ *      machine's checkout of the same repo);
+ *   2. no remote → a salt persisted at `<root>/.vx/workspace-id` (the
+ *      checkout keeps a stable identity across runs; `.vx/` is already
+ *      gitignored infrastructure);
+ *   3. unwritable `.vx/` → the root path itself (stable per machine).
+ * One `git` spawn behind try/catch; call sites gate on telemetry being
+ * active so a plain run never pays it. Never throws.
+ */
+export function captureWorkspaceIdentity(workspaceRoot: string): WorkspaceIdentity {
+  const base = workspaceRoot.replace(/\/+$/, '').split('/').pop() || 'workspace'
+  try {
+    const proc = Bun.spawnSync({
+      // `config --get`, NOT `remote get-url`: get-url applies insteadOf
+      // rewrites, so two developers mirroring the same repo through
+      // different proxies would derive different workspace ids. The raw
+      // configured URL is the identity.
+      cmd: ['git', '-C', workspaceRoot, 'config', '--get', 'remote.origin.url'],
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    if (proc.exitCode === 0) {
+      const url = new TextDecoder().decode(proc.stdout).trim()
+      if (url.length > 0) {
+        const normalized = normalizeRemoteUrl(url)
+        const name = normalized.split('/').pop() || base
+        return { id: xxh3hex(normalized), name }
+      }
+    }
+  } catch {
+    // git unavailable — fall through to the salt.
+  }
+  try {
+    const saltPath = path.join(workspaceRoot, '.vx', 'workspace-id')
+    let salt: string
+    try {
+      salt = fs.readFileSync(saltPath, 'utf8').trim()
+      if (salt.length === 0) throw new Error('empty')
+    } catch {
+      salt = ulid()
+      fs.mkdirSync(path.dirname(saltPath), { recursive: true })
+      fs.writeFileSync(saltPath, salt + '\n')
+    }
+    return { id: xxh3hex(salt), name: base }
+  } catch {
+    return { id: xxh3hex(workspaceRoot), name: base }
+  }
+}