@vzn/vx 0.0.521 → 0.0.523

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.521",
+  "version": "0.0.523",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.521",
-    "@vzn/vx-linux-arm64": "0.0.521",
-    "@vzn/vx-darwin-x64": "0.0.521",
-    "@vzn/vx-darwin-arm64": "0.0.521"
+    "@vzn/vx-linux-x64": "0.0.523",
+    "@vzn/vx-linux-arm64": "0.0.523",
+    "@vzn/vx-darwin-x64": "0.0.523",
+    "@vzn/vx-darwin-arm64": "0.0.523"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/cache.ts

@@ -34,6 +34,7 @@
 import { Database } from 'bun:sqlite'
 import {
   accessSync,
+  chmodSync,
   closeSync,
   constants,
   existsSync,
@@ -169,38 +170,6 @@ function outOfFdsAtOpen(dbFile: string, err: unknown): UserError | undefined {
   }
 }
 
-/** Say once, on the channel the opener has, that an upgrade emptied the index. */
-export function noteSchemaReset(cache: Cache, warn: (message: string) => void): void {
-  if (cache.storeFallback !== null) {
-    warn(
-      `[vx] shared cache store ${cache.storeFallback} is not usable; entries stay in ${cache.storeDir ?? 'this workspace'}, where no other workspace hits them`,
-    )
-  }
-  if (cache.storeMoved !== null) {
-    const { from, to } = cache.storeMoved
-    warn(
-      `[vx] cache entries now live in the shared store ${to}; the ones in ${from} miss once, and \`vx cache prune\` reclaims their artifacts`,
-    )
-  }
-  if (cache.storeReset !== null) {
-    const { from, to } = cache.storeReset
-    warn(
-      `[vx] shared cache store ${cache.storeDir} re-indexed: schema ${from} → ${to} (vx version changed); its artifacts stay and are indexed again as tasks hit them`,
-    )
-  }
-  if (cache.formatChange !== null) {
-    const { from, to } = cache.formatChange
-    warn(
-      `[vx] cache format changed: ${from} → ${to} (vx version changed); every cached task misses once and re-saves, and the old entries, never read again, age out under \`vx cache prune --older-than\` or \`cacheRetention\``,
-    )
-    return
-  }
-  if (cache.schemaReset === null) return
-  const { from, to } = cache.schemaReset
-  warn(
-    `[vx] cache index reset: schema ${from} → ${to} (vx version changed); run history starts over, and each artifact is indexed again when its task next hits`,
-  )
-}
 // SCHEMA history (drop+recreate on mismatch; pre-alpha, no migrations):
 //   v20: file_hashes.content_hash (git blob OIDs).
 //   v21: dropped the unused outputs_hash column (pure-input hashing).
@@ -459,7 +428,16 @@ function ensurePrivateDir(dir: string): string | null {
   if (!st.isDirectory()) return `${dir} is not a directory`
   const uid = process.getuid?.()
   if (uid !== undefined && st.uid !== uid) return `${dir} belongs to another user`
-  if ((st.mode & 0o077) !== 0) return `${dir} is open to other users (chmod 700 it)`
+  // The user's own directory open to others (a `~/.vx` made at the
+  // default umask, 0755) is vx's to close: refusing it left the store
+  // unused on a stock macOS home (owner, 2026-10-06: "you should own it").
+  if ((st.mode & 0o077) !== 0) {
+    try {
+      chmodSync(dir, 0o700)
+    } catch (err) {
+      return `${dir} is open to other users and chmod 700 failed (${errorText(err)})`
+    }
+  }
   return null
 }
 
@@ -550,8 +528,7 @@ export class Cache implements CacheLayer {
 
   /**
    * The store this open was asked for and could not use, with why: the
-   * entries went to a store inside `cacheDir` instead. Said once by
-   * `noteSchemaReset`.
+   * entries went to a store inside `cacheDir` instead.
    */
   readonly storeFallback: string | null = null
 
@@ -561,24 +538,22 @@ export class Cache implements CacheLayer {
   /**
    * Set when THIS open found an index written by another `SCHEMA_VERSION`
    * and dropped every table. The next open sees the current version and
-   * reports null, so whoever opened first is the one that can say so —
-   * `noteSchemaReset` is that one line, at every opener that has a
-   * channel. Without it an upgrade empties the cache and the history in
-   * silence, and the all-miss run that follows looks like a bug.
+   * reports null. vx prints nothing for it: the cache is vx's to keep
+   * (owner, 2026-10-06).
    */
   readonly schemaReset: SchemaReset | null = null
 
   /**
    * Set when THIS open found entries written under another
    * `CACHE_VERSION`: the index survives, but no old key is derived again,
-   * so every cached task misses once. Reported by `noteSchemaReset`.
+   * so every cached task misses once. Not printed, like `schemaReset`.
    */
   readonly formatChange: SchemaReset | null = null
 
   /**
    * Set when THIS open found the shared store written under another
    * `SCHEMA_VERSION` and dropped its inventory; the artifacts stay and are
-   * indexed again as they hit. Reported by `noteSchemaReset`.
+   * indexed again as they hit. Never printed: the cache is vx's to keep.
    */
   readonly storeReset: SchemaReset | null = null
 

package/src/cache/git-inputs.ts

@@ -214,6 +214,22 @@ export class GitFilesCache extends Map<string, readonly string[]> {
     this.dirty = dirty
   }
 
+  /** The populate's `git var -l`, for `configValue`. */
+  private vars: Map<string, string> | null = null
+
+  setGitVars(listing: string | null): void {
+    this.vars = listing === null ? null : gitVarList(listing)
+  }
+
+  /**
+   * A config key's value as `git config --get` answers it (the last one),
+   * from the populate's `git var -l`: null when the config has none,
+   * undefined when no listing was read.
+   */
+  configValue(key: string): string | null | undefined {
+    return this.vars === null ? undefined : (this.vars.get(key) ?? null)
+  }
+
   markOutputsChanged(projectDir: string, relPaths: readonly string[]): void {
     this.recordChanged(projectDir, relPaths)
     // The workspace-wide partition sees the same files under
@@ -774,6 +790,12 @@ async function dropFilteredOids(
     pathspecs: readonly string[]
     gitVars: string
     spawnGit: (a: string[], stdin?: string) => Promise<GitRun | null>
+    /**
+     * The same `check-attr`, already started over every listed index entry
+     * (a superset of `trusted`) because `attributesInIndex` fired before
+     * `status` was back.
+     */
+    early?: Promise<GitRun | null> | undefined
   },
 ): Promise<void> {
   if (trusted.size === 0) return
@@ -823,14 +845,48 @@ async function dropFilteredOids(
   // blob's OID keyed an edit git calls clean, and the run replayed the old
   // output (item 978). Git LFS is a `filter` as well: its files are hashed
   // from disk now, the one honest identity of what a task reads.
-  const res = await args.spawnGit(
-    ['check-attr', '--stdin', '-z', 'text', 'eol', 'ident', 'filter', 'working-tree-encoding'],
-    [...trusted.keys()].join('\0'),
-  )
+  const res = await (args.early ?? args.spawnGit(CHECK_ATTR, [...trusted.keys()].join('\0')))
   if (res === null || res.exitCode !== 0) return
   for (const rel of parseCheckAttrOutput(res.stdout)) trusted.delete(rel)
 }
 
+const CHECK_ATTR = [
+  'check-attr',
+  '--stdin',
+  '-z',
+  'text',
+  'eol',
+  'ident',
+  'filter',
+  'working-tree-encoding',
+]
+
+/**
+ * The filter gate's half that needs only the index listing: an attributes
+ * file tracked in it, in `$GIT_DIR/info/attributes`, or above the scanned
+ * dirs. When it fires, `dropFilteredOids` is sure to ask `check-attr`, so the
+ * enumeration starts it beside `status` (~8 ms on this repo, U-3)
+ * instead of after it. When it does not, the whole gate decides later.
+ */
+function attributesInIndex(args: {
+  tracked: readonly string[]
+  workspaceRoot: string
+  gitDir: string
+  gitPrefix: string
+  pathspecs: readonly string[]
+}): boolean {
+  if (
+    args.gitDir !== '' &&
+    existsSync(path.resolve(args.workspaceRoot, args.gitDir, 'info', 'attributes'))
+  ) {
+    return true
+  }
+  for (const rel of args.tracked) {
+    if (rel === '.gitattributes' || rel.endsWith('/.gitattributes')) return true
+  }
+  return attributesAbove(args)
+}
+
 /**
  * The repository root, derived from the workspace root and git's own
  * `--show-prefix` (the repo→workspace path). Exact and free: the prefix
@@ -1095,6 +1151,8 @@ export interface GitEnumeration {
   trusted: Map<string, string>
   /** Whether the worktree had uncommitted changes; null when `git status` failed. */
   dirty: boolean | null
+  /** `git var -l`'s listing (merged config, then git's variables); null when it failed. */
+  vars: string | null
   /**
    * What `git status` listed, workspace-relative: modified, staged or deleted
    * paths (both sides of a rename) and untracked files. Null when it failed.
@@ -1259,7 +1317,20 @@ export async function startGitEnumeration(
     }
   }
   const indexKeyRead = readIndexKey()
-  const [ls, status, vars] = await running
+  const gitPrefix = facts?.prefix ?? ''
+  const gitDir = facts?.commonDir ?? ''
+  const ls = await listing
+  const parsedLs =
+    ls !== null && ls.exitCode === 0
+      ? parseLsFilesOutput(ls.stdout.length === 0 ? [] : ls.stdout.split('\0'), ls.undecodable)
+      : undefined
+  const early =
+    parsedLs !== undefined &&
+    parsedLs.oids.size > 0 &&
+    attributesInIndex({ tracked: parsedLs.files, workspaceRoot, gitDir, gitPrefix, pathspecs })
+      ? spawnGit(CHECK_ATTR, [...parsedLs.oids.keys()].join('\0'))
+      : undefined
+  const [, status, vars] = await running
   // The key stands for the index `ls-files` listed only when that index
   // was written before the enumeration began (git writes it by rename, so
   // the stamp moves with any write) and is still in place after it: a
@@ -1281,20 +1352,14 @@ export async function startGitEnumeration(
   if (ls === null) {
     throw gitSpawnRefusal(workspaceRoot)
   }
-  if (ls.exitCode !== 0) {
+  if (parsedLs === undefined) {
     const stderr = ls.stderr.trim()
     throw new UserError(
       `vx requires git: ${workspaceRoot} is not inside a git work tree. ` +
         `Run 'git init' in your workspace root.${stderr ? ` (git: ${stderr})` : ''}`,
     )
   }
-  const {
-    files: tracked,
-    oids,
-    flagged,
-    gitlinks,
-    undecodable,
-  } = parseLsFilesOutput(ls.stdout.length === 0 ? [] : ls.stdout.split('\0'), ls.undecodable)
+  const { files: tracked, oids, flagged, gitlinks, undecodable } = parsedLs
   // Normalize `status`'s repo-root-relative paths to workspace-relative (strip
   // the `--show-prefix`) so the dirty set is keyed identically to the trusted
   // OID map. Without this, when the workspace root is a git subdir, a modified
@@ -1302,8 +1367,6 @@ export async function startGitEnumeration(
   // a STALE cache hit serving old outputs. Empty prefix (workspace == git root,
   // the common case) is a zero-cost no-op. Paths above the workspace can't be
   // inputs, so they drop out of the set.
-  const gitPrefix = facts?.prefix ?? ''
-  const gitDir = facts?.commonDir ?? ''
   const parsedStatus =
     status !== null && status.exitCode === 0
       ? parseStatusOutput(status.stdout, status.undecodable)
@@ -1357,6 +1420,7 @@ export async function startGitEnumeration(
     pathspecs,
     gitVars: vars !== null && vars.exitCode === 0 ? vars.stdout : '',
     spawnGit,
+    early,
   })
   if (vars !== null && vars.exitCode === 0 && fileModeIgnored(vars.stdout)) {
     restampModes(trusted, workspaceRoot)
@@ -1368,6 +1432,7 @@ export async function startGitEnumeration(
     all,
     trusted,
     dirty: worktreeDirty,
+    vars: vars !== null && vars.exitCode === 0 ? vars.stdout : null,
     changed: dirty === null ? null : [...dirty, ...untracked],
     untracked: dirty === null ? null : untracked,
     undecodable,
@@ -1436,6 +1501,7 @@ export async function applyGitEnumeration(
   await dropResizedOids(enumeration, memo)
   const { all, trusted } = enumeration
   cache.setWorktreeDirty(enumeration.dirty)
+  cache.setGitVars(enumeration.vars)
   cache.enumeratedAtMs = enumeration.startedAtMs
   cache.markUndecodable(enumeration.undecodable.map((rel) => path.join(workspaceRoot, rel)))
   // Sort once, then each project's files are a contiguous range found

package/src/cache/index.ts

@@ -25,7 +25,6 @@ export {
   FILE_HASH_RACY_MS,
   OUTPUT_DIRS_RACY_MS,
   racyWindowMs,
-  noteSchemaReset,
   type SchemaReset,
   SCHEMA_VERSION,
 } from './cache.js'

package/src/cache/output-index.ts

@@ -8,6 +8,12 @@
 
 /** `mtime_ms` of a recorded output prefix that did not exist when the snapshot was taken. */
 const ABSENT_DIR_MTIME = -1
+/**
+ * `mtime_ms` of a recorded output prefix that was a regular file: a literal
+ * output naming one (`public/app.js`). The set under it is the file alone
+ * while it stays a regular file; its bytes are the per-file check's.
+ */
+const FILE_PREFIX_MTIME = -2
 
 import type { Database } from 'bun:sqlite'
 import { inHashes, lazyStatement } from './schema.js'
@@ -244,7 +250,14 @@ export class OutputIndex {
         }
         return false
       }
-      if (!st.isDirectory()) return false
+      if (!st.isDirectory()) {
+        // A literal output naming a file walked its glob on every hit: two
+        // of this repo's site tasks, ~6 ms of each warm run (U-5).
+        if (!isPrefix || !st.isFile()) return false
+        rows.push([rel, FILE_PREFIX_MTIME])
+        files.push(rel)
+        return true
+      }
       rows.push([rel, st.mtimeMs])
       if (rows.length > OUTPUT_DIRS_CAP) return false
       let entries
@@ -379,6 +392,7 @@ export class OutputIndex {
         return r.mtimeMs === ABSENT_DIR_MTIME
       }
       if (r.mtimeMs === ABSENT_DIR_MTIME) return false
+      if (r.mtimeMs === FILE_PREFIX_MTIME) return st.isFile()
       return st.isDirectory() && Math.abs(st.mtimeMs - r.mtimeMs) < 1
     })
     return results.every(Boolean)

package/src/cli/cache.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { Cache, noteSchemaReset } from '../cache/index.js'
+import { Cache } from '../cache/index.js'
 import { flagHint, refusedWord, seeHelp } from './help.js'
 import { nearest, parseDuration, parseSize } from '../util/index.js'
 import { acquireRunLock } from '../orchestrator/index.js'
@@ -189,7 +189,6 @@ async function pruneCmd(args: readonly string[]): Promise<number> {
   // stack (an unprivileged user on a root-owned `.vx`, 2026-09-16). A dry
   // run only reads, and reads a read-only cache fine.
   if (!parsed.dryRun) cache.assertWritable()
-  noteSchemaReset(cache, warnToStderr)
   // A prune beside a run on this workspace evicts what the run has just
   // probed as hits, whose `accessed_at` bumps it has not flushed yet; the
   // run then re-runs those tasks (upstream survey, nx#36688). So a prune

package/src/cli/last.ts

@@ -5,7 +5,7 @@
 // Read-only — no config evaluation, no re-hash, no cache probe.
 
 import type { Database } from 'bun:sqlite'
-import { Cache, noteSchemaReset } from '../cache/index.js'
+import { Cache } from '../cache/index.js'
 import { formatBytes } from './format.js'
 import { flagHint, seeHelp } from './help.js'
 import {
@@ -21,7 +21,7 @@ import {
 } from '../orchestrator/index.js'
 import { formatElapsed, UserError } from '../util/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
-import { cliCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
+import { cliCacheDir, parseCacheDirFlag } from './workspace-config.js'
 
 interface LastArgs {
   runId?: string
@@ -232,7 +232,6 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
 
   const root = await findWorkspaceRoot(process.cwd())
   const cache = Cache.inspect(await cliCacheDir(root, parsed.cacheDir))
-  noteSchemaReset(cache, warnToStderr)
   try {
     const db = cache.dbHandle()
     // Nothing recorded at all is its own answer: `--failed` said "no

package/src/cli/why.ts

@@ -6,7 +6,7 @@
 // no config evaluation, no re-hash.
 
 import path from 'node:path'
-import { Cache, noteSchemaReset } from '../cache/index.js'
+import { Cache } from '../cache/index.js'
 import { flagHint, seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
 import {
@@ -18,7 +18,7 @@ import {
 } from '../orchestrator/index.js'
 import { MASKED, nearMatches, printable, UserError } from '../util/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
-import { cliCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
+import { cliCacheDir, parseCacheDirFlag } from './workspace-config.js'
 
 interface WhyArgs {
   target?: string
@@ -185,7 +185,6 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
 
   const root = await findWorkspaceRoot(process.cwd())
   const cache = Cache.inspect(await cliCacheDir(root, parsed.cacheDir))
-  noteSchemaReset(cache, warnToStderr)
   try {
     const db = cache.dbHandle()
     const taskId = resolveTarget(cache, await rootSpelled(root, parsed.target))

package/src/cli/workspace-config.ts

@@ -8,7 +8,7 @@ import { existsSync } from 'node:fs'
 import path from 'node:path'
 import type { WorkspaceConfig } from '../config.js'
 import { UserError } from '../util/index.js'
-import { Cache, noteSchemaReset } from '../cache/index.js'
+import { Cache } from '../cache/index.js'
 import { discoverProjects, loadProjects, loadWorkspacePlugins } from '../orchestrator/index.js'
 import type { VxPlugin } from '../orchestrator/index.js'
 import {
@@ -147,7 +147,6 @@ export async function loadCliProjects(
           'open',
           opts.cacheDir === undefined ? ws.storeRoot : null,
         )
-  if (cache !== null) noteSchemaReset(cache, warnToStderr)
   try {
     const loaded = await loadProjects({
       workspaceRoot,

package/src/orchestrator/doctor.ts

@@ -7,7 +7,7 @@
 
 import os from 'node:os'
 import path from 'node:path'
-import { Cache, CACHE_VERSION, noteSchemaReset, SCHEMA_VERSION } from '../cache/index.js'
+import { Cache, CACHE_VERSION, SCHEMA_VERSION } from '../cache/index.js'
 import { PLUGIN_HOOKS } from '../config.js'
 import {
   cgroupCpuQuota,
@@ -154,7 +154,6 @@ async function collectWorkspaceInfo(
   const metas = await discoverProjects(await loadWorkspace(root, reads), plugins, cacheDir, warn)
   const storeRoot = opts.cacheDir === undefined ? resolveStoreRoot(root, workspaceConfig) : null
   const cache = Cache.inspect(cacheDir)
-  noteSchemaReset(cache, warn)
   let stats
   let orphans
   let flaky: FlakyTask[]

package/src/orchestrator/prepare.ts

@@ -12,7 +12,6 @@ import type { WorkspaceConfig } from '../config.js'
 import { beginRun, mark, nearest, UserError } from '../util/index.js'
 import {
   Cache,
-  noteSchemaReset,
   type CacheLayer,
   type CachePolicy,
   FULL_CACHE_POLICY,
@@ -287,7 +286,6 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     storeRoot,
   )
   localCache.assertWritable()
-  noteSchemaReset(localCache, (m) => log.status(m))
   // Two digests from one read: the config-evaluation cache keys on every
   // file (a config may import a dependency), the task keys on the files no
   // plugin claims (`VxPlugin.fingerprint`).

package/src/orchestrator/run-context.ts

@@ -4,9 +4,11 @@
 // 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.
+// Cost: HEAD read from `.git` on every run (`captureGitContext`), plus
+// `refs/remotes/origin/HEAD` and the enumeration's `remote.origin.url`
+// only when a plugin declares the `telemetry` capability — nobody else
+// needs those fields. Each falls back to a `git` spawn where the files or
+// the enumeration cannot answer.
 
 import fs from 'node:fs'
 import os from 'node:os'
@@ -115,28 +117,9 @@ 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())
-    }
-    // Reftable storage (`git init --ref-format=reftable`, git 2.45): HEAD
-    // names `refs/heads/.invalid` and the refs live in `reftable/`, so the
-    // files say nothing true about HEAD. A leftover `packed-refs` there was
-    // read as the answer; git is asked instead.
-    if (
-      fs.existsSync(path.join(gitDir, 'reftable')) ||
-      fs.existsSync(path.join(commonDir, 'reftable'))
-    ) {
-      return null
-    }
+    const dirs = refDirsOf(workspaceRoot)
+    if (dirs === null) return null
+    const { gitDir, commonDir } = dirs
     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 }
@@ -166,6 +149,57 @@ function readHeadDirect(
   }
 }
 
+/**
+ * The git dir and common dir behind `workspaceRoot` when its refs are files
+ * this code reads: a `.git` directory or a `.git` FILE (`gitdir: …`, a linked
+ * worktree, whose shared refs live under `commondir`). Null for a reftable
+ * repository (`git init --ref-format=reftable`, git 2.45): HEAD names
+ * `refs/heads/.invalid` and the refs live in `reftable/`, so the files say
+ * nothing true. A leftover `packed-refs` there was read as the answer.
+ * Throws when there is no `.git` at the root (a workspace in a subdirectory).
+ */
+function refDirsOf(workspaceRoot: string): { gitDir: string; commonDir: string } | null {
+  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())
+  }
+  if (
+    fs.existsSync(path.join(gitDir, 'reftable')) ||
+    fs.existsSync(path.join(commonDir, 'reftable'))
+  ) {
+    return null
+  }
+  return { gitDir, commonDir }
+}
+
+/**
+ * `refs/remotes/origin/HEAD`'s target from the files, as `git symbolic-ref
+ * --short` names it (`origin/main`): `undefined` when the files cannot say
+ * (no `.git` at the root, reftable), null when there is no such symbolic
+ * ref. A symbolic ref is never packed, so a missing file is git's answer
+ * too.
+ */
+function readOriginHeadDirect(workspaceRoot: string): string | null | undefined {
+  try {
+    const dirs = refDirsOf(workspaceRoot)
+    if (dirs === null) return undefined
+    const file = path.join(dirs.commonDir, 'refs', 'remotes', 'origin', 'HEAD')
+    if (!fs.existsSync(file)) return null
+    const ref = /^ref:\s*refs\/remotes\/(.+)$/.exec(fs.readFileSync(file, 'utf8').trim())
+    return ref === null ? undefined : ref[1]!
+  } catch {
+    return undefined
+  }
+}
+
 /**
  * The branch a CI provider says this checkout came from, or null.
  *
@@ -221,30 +255,34 @@ export function captureDefaultBranch(
     }
   }
 
-  try {
-    const proc = Bun.spawnSync({
-      cmd: [
-        executablePath('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
+  // The file first, as `captureGitContext` reads HEAD: a spawn here was
+  // ~8 ms of every run a telemetry plugin is declared in.
+  let ref = readOriginHeadDirect(workspaceRoot)
+  if (ref === undefined) {
+    ref = null
+    try {
+      const proc = Bun.spawnSync({
+        cmd: [
+          executablePath('git'),
+          '-C',
+          workspaceRoot,
+          'symbolic-ref',
+          '--short',
+          'refs/remotes/origin/HEAD',
+        ],
+        stdout: 'pipe',
+        stderr: 'ignore',
+      })
+      if (proc.exitCode === 0) ref = new TextDecoder().decode(proc.stdout).trim()
+    } catch {
+      // git unavailable / no remote HEAD ref: null.
     }
-  } catch {
-    // git unavailable / no remote HEAD ref: null.
   }
-  return null
+  if (ref === null) return null
+  // `refs/remotes/origin/HEAD` → `origin/main`; strip the remote prefix.
+  const slash = ref.indexOf('/')
+  const name = slash >= 0 ? ref.slice(slash + 1) : ref
+  return name.length > 0 ? name : null
 }
 
 // Recognized CI env vars in match-priority order. The first whose value
@@ -324,28 +362,38 @@ export function normalizeRemoteUrl(raw: string): string {
  *      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.
+ * The URL comes from the run's own `git var -l` when it has one, else 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 {
+export function captureWorkspaceIdentity(
+  workspaceRoot: string,
+  /**
+   * `remote.origin.url` as the run's enumeration read it (`git var -l`, the
+   * same merged config): null when it has none. Undefined asks git.
+   */
+  originUrl?: string | null,
+): 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: [executablePath('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 }
-      }
+    let url = originUrl ?? ''
+    if (originUrl === undefined) {
+      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: [executablePath('git'), '-C', workspaceRoot, 'config', '--get', 'remote.origin.url'],
+        stdout: 'pipe',
+        stderr: 'ignore',
+      })
+      if (proc.exitCode === 0) url = new TextDecoder().decode(proc.stdout)
+    }
+    url = url.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.

package/src/orchestrator/run.ts

@@ -720,9 +720,13 @@ async function runOnBus(
     // but declines still pays — its answer is only knowable by asking.
     const hasTelemetryPlugin = prepared.plugins.some((p) => p.telemetry !== undefined)
     if (hasTelemetryPlugin || options.telemetrySinks !== undefined) {
-      // Workspace identity (telemetry v2): one git spawn, paid only when a
-      // telemetry consumer can exist — a plain run never reaches here.
-      const wsIdentity = captureWorkspaceIdentity(workspaceRoot)
+      // Workspace identity (telemetry v2), paid only when a telemetry
+      // consumer can exist — a plain run never reaches here. The remote URL
+      // is the enumeration's `git var -l`: a spawn here cost ~4 ms.
+      const wsIdentity = captureWorkspaceIdentity(
+        workspaceRoot,
+        gitFilesCache.configValue('remote.origin.url'),
+      )
       runContextRecord = {
         runId,
         vxVersion: VERSION,

package/src/workspace/config-cache.ts

@@ -165,6 +165,10 @@ const IMPURE_LITERAL_RE = /constructor|__proto__|prototype/
 const IMPORT_RE =
   /\b(?:import|export)\b(?:(?!\b(?:import|export)\b)[^;])*?\bfrom\s*\0(\d+)\0|\bimport\s*\0(\d+)\0/g
 
+// `import` as a keyword. Followed by `:` it is a property key (a task named
+// `import`): no import form, static or dynamic, puts a colon after the word.
+const IMPORT_WORD_RE = /\bimport\b(?!\s*:)/g
+
 /**
  * Every static import in `source` as its specifier and statement, or `null`
  * when the source cannot be lexed or holds an `import` no form above
@@ -181,9 +185,9 @@ function staticImports(
   let seen = 0
   for (const m of code.matchAll(IMPORT_RE)) {
     imports.push({ spec: strings[Number(m[1] ?? m[2])]!, statement: m[0] })
-    seen += m[0].match(/\bimport\b/g)?.length ?? 0
+    seen += m[0].match(IMPORT_WORD_RE)?.length ?? 0
   }
-  if (seen !== (code.match(/\bimport\b/g)?.length ?? 0)) return null
+  if (seen !== (code.match(IMPORT_WORD_RE)?.length ?? 0)) return null
   return { code, strings, imports }
 }
 

package/src/workspace/migration.ts

@@ -289,7 +289,7 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     files.push({
       relPath: relPosix(root, abs),
       abs,
-      contents: renderConfigFile(source, p, verb, format),
+      contents: renderConfigFile(p, format),
     })
   }
   for (const f of plan.extraFiles) {
@@ -302,7 +302,8 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   const hasWorkspaceFile = (
     await Promise.all(WORKSPACE_CONFIG_FILENAMES.map((n) => Bun.file(path.join(root, n)).exists()))
   ).some(Boolean)
-  if (!hasWorkspaceFile) {
+  // A plan may bring its own (vx-migrate declares the plugins it detects).
+  if (!hasWorkspaceFile && !plan.extraFiles.some((f) => f.relPath === workspaceName)) {
     const abs = path.join(root, workspaceName)
     files.push({ relPath: relPosix(root, abs), abs, contents: workspaceFile(format) })
   }
@@ -550,11 +551,8 @@ function exampleConfig(format: MigrationFormat): string {
 // `import { defineWorkspace } from '@vzn/vx'` loads a SECOND copy of core
 // into every run — measured 2026-09-09 at ~17 ms on a two-package
 // workspace, a fifth of the whole run — for an identity function.
-const WORKSPACE_BODY = `// Plugins are consulted in this order; running here and caching in
-// .vx/cache are the floor under all of them, so an empty list is a
-// complete workspace. Add a remote cache, a remote executor or telemetry
-// as one entry each — those imports are the runtime ones.
-export default { plugins: [] }`
+// No explanatory comment: the file is the user's (owner, 2026-10-06).
+const WORKSPACE_BODY = `export default { plugins: [] }`
 
 function workspaceFile(format: MigrationFormat): string {
   return format === 'ts'
@@ -586,22 +584,18 @@ function renderValue(v: unknown, indent: string): string {
   return `{\n${body.join('\n')}\n${indent}}`
 }
 
-function renderConfigFile(
-  source: string,
-  p: GeneratedProject,
-  verb: string,
-  format: MigrationFormat,
-): string {
+function renderConfigFile(p: GeneratedProject, format: MigrationFormat): string {
   // A type-only import: the editor type-checks against the installed
   // package, and Bun erases it, so the config loads in a workspace that
   // runs the vx binary without the package installed. `mjs` is the same
   // object with nothing to erase.
-  const lines: string[] = [
-    `// Generated by \`${verb}\` from ${source}.${p.tasks.some((t) => t.todos.length > 0) ? ' Review the TODO(vx-migrate) comments.' : ''}`,
-  ]
+  // No "generated by" header: the file is the user's from here (owner,
+  // 2026-10-06), and each TODO(vx-migrate) sits on its own task.
+  const lines: string[] = []
   if (format === 'ts') lines.push("import type { ProjectConfig } from '@vzn/vx/config'")
   if (p.importLines.length > 0) lines.push(...p.importLines)
-  lines.push('', 'export default {')
+  if (lines.length > 0) lines.push('')
+  lines.push('export default {')
   if (p.tags !== undefined && p.tags.length > 0) lines.push(`  tags: ${renderValue(p.tags, '  ')},`)
   lines.push('  tasks: {')
   for (const t of p.tasks) {