@vzn/vx 0.0.16 → 0.0.18

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 the dashboard's branch column 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

package/src/orchestrator/run-report.ts

@@ -1,64 +1,66 @@
-// Markdown run report (`vx run --report=markdown`). A moon-style table —
-// one row per task plus a header line of totals — written verbatim to
-// stdout after a run so CI can append it to a step summary
-// (`vx run ci --report=markdown >> $GITHUB_STEP_SUMMARY`). Pure: the
-// run's finished outcomes in, a markdown string out. No ANSI, no live
-// region — keep it machine-clean and diffable.
+// Markdown run report (`vx run --report=markdown` / `--report-file=<path>`).
+// A moon-style table — one row per task plus a header line of totals —
+// rendered after a run so CI can put it in a step summary
+// (`vx run ci --report-file="$GITHUB_STEP_SUMMARY"`). Pure: the run's
+// finished outcomes in, a markdown string out. No ANSI, no live region —
+// keep it machine-clean and diffable.
+//
+// Machine-clean is a property of this STRING, not of stdout: the status
+// logger shares that stream, so redirecting it captures the whole run log
+// too. `--report-file` is the sink that carries the property end to end.
 
-import type { RunResult } from './protocol.js'
 import type { OutcomeView } from './events.js'
 
 /**
- * Outcome buckets for the report header. Mirrors the terminal summary's
- * `tallyOutcomes` partition (success counts hits; `aborted` is no work
- * and excluded), but derives from the serializable `OutcomeView` the CLI
- * holds after a run rather than the in-process `TaskOutcome` — so it
- * needs no graph back-ref and stays self-contained here.
+ * One finished run, reduced to what a report needs. Used to live in
+ * `protocol.ts` as the return type of the whole-run `backend` seam; that
+ * seam is gone (a run always executes in-process — see
+ * `docs/modules/executor.md`), so the shape lives with its only consumer.
  */
-interface ReportTally {
-  total: number
-  successful: number
-  failed: number
-  skipped: number
-  cached: number
+export interface RunResult {
+  ok: boolean
+  outcomes: OutcomeView[]
+}
+import { tallyViews, type Tally } from './tally.js'
+
+/**
+ * The report header's numbers. The outcome BUCKETS come from the shared
+ * `tallyViews` — the same rules the terminal summary and `--summarize` use,
+ * so three surfaces describing one run cannot disagree. Only the two
+ * durations are report-specific.
+ *
+ * This used to be a private copy of the partition, and it drifted: it had no
+ * group filter (it could not have one — `OutcomeView` had no `isGroup`), so
+ * every organizational node was counted as a successful task and rendered as
+ * a row claiming `success | miss | 0ms`.
+ */
+interface ReportTally extends Tally {
   /** Wall-clock ms summed over tasks that actually executed (misses). */
   executedMs: number
-  /** Wall-clock ms summed over cache hits — the work the cache skipped. */
+  /**
+   * Ms of work the cache SKIPPED — the sum of the hits' STORED exec times.
+   * Deliberately not `durationMs`, which for a hit is the restore this run
+   * paid: summing that reported a 2.01 s task as "6ms saved".
+   */
   savedMs: number
 }
 
 function tally(outcomes: readonly OutcomeView[]): ReportTally {
-  const t: ReportTally = {
-    total: 0,
-    successful: 0,
-    failed: 0,
-    skipped: 0,
-    cached: 0,
-    executedMs: 0,
-    savedMs: 0,
-  }
+  const t: ReportTally = { ...tallyViews(outcomes), executedMs: 0, savedMs: 0 }
   for (const o of outcomes) {
-    // A child killed by a shutdown signal (Ctrl-C teardown) is no work —
-    // excluded from totals and every bucket, like the terminal tally.
-    if (o.status === 'aborted') continue
-    t.total++
+    if (o.isGroup === true) continue
     switch (o.status) {
       case 'success':
-        t.successful++
+      case 'failed':
         t.executedMs += o.durationMs
         break
       case 'cache-hit':
       case 'cache-hit-remote':
-        t.successful++
-        t.cached++
-        t.savedMs += o.durationMs
-        break
-      case 'failed':
-        t.failed++
-        t.executedMs += o.durationMs
-        break
-      case 'skipped':
-        t.skipped++
+        // An outcome that doesn't know what it skipped contributes nothing:
+        // better to omit the claim than to substantiate it with the restore
+        // cost. (Only reachable across a version skew — every hit this
+        // binary produces carries the stored duration.)
+        t.savedMs += o.storedDurationMs ?? 0
         break
     }
   }
@@ -98,6 +100,24 @@ function fmtDuration(ms: number): string {
   return `${(ms / 1000).toFixed(2)}s`
 }
 
+/**
+ * Make a value safe inside a GFM table cell. Task names are arbitrary TS
+ * object keys and the loader accepts `|` and newlines, either of which
+ * silently breaks the table on the consumer (`>> $GITHUB_STEP_SUMMARY`):
+ * a bare pipe adds a column, a newline splits the row.
+ *
+ * Exported because this file is not the only markdown table describing a run:
+ * the cloud plugin's GitHub job summary renders the same data from the same
+ * unvalidated names and shipped WITHOUT this escape, so a `|` in a task name
+ * or a `--verify` output path shifted its columns. One definition, so the two
+ * cannot disagree about what a cell may contain.
+ */
+export function escapeMarkdownCell(value: string): string {
+  return value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ')
+}
+
+const cell = escapeMarkdownCell
+
 /**
  * Render the finished run as a markdown report. A header line of totals
  * followed by a per-task table. Self-contained — everything is derived
@@ -105,13 +125,15 @@ function fmtDuration(ms: number): string {
  */
 export function formatRunReportMarkdown(result: RunResult): string {
   const t = tally(result.outcomes)
+  const cached = t.cachedLocal + t.cachedRemote
   const parts = [
     `**${t.total} task${t.total === 1 ? '' : 's'}**`,
     `${t.successful} success`,
     `${t.failed} failed`,
-    `${t.cached} cached`,
+    `${cached} cached`,
   ]
   if (t.skipped > 0) parts.push(`${t.skipped} skipped`)
+  if (t.aborted > 0) parts.push(`${t.aborted} aborted`)
   parts.push(`${fmtDuration(t.executedMs)} total`)
   if (t.savedMs > 0) parts.push(`${fmtDuration(t.savedMs)} saved`)
 
@@ -123,9 +145,14 @@ export function formatRunReportMarkdown(result: RunResult): string {
   lines.push('| Task | Status | Cache | Duration |')
   lines.push('| --- | --- | --- | --- |')
   for (const o of result.outcomes) {
-    if (o.status === 'aborted') continue
+    // A group node did no work: no command, no cache decision, 0ms. Rendering
+    // one as `success | miss | 0ms` invents a task the user never wrote a
+    // command for. Same exclusion the header's tally makes.
+    if (o.isGroup === true) continue
     lines.push(
-      `| ${o.taskId} | ${statusWord(o)} | ${cacheWord(o)} | ${fmtDuration(o.durationMs)} |`,
+      `| ${cell(o.taskId)} | ${cell(statusWord(o))} | ${cell(cacheWord(o))} | ${cell(
+        fmtDuration(o.durationMs),
+      )} |`,
     )
   }
   return lines.join('\n') + '\n'