@vzn/vx 0.0.635 → 0.0.637

package/src/exec/env.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
+import { ESSENTIAL_ENV } from '../util/index.js'
 
 // Build the environment exposed to a task.
 //
@@ -9,37 +10,6 @@ import path from 'node:path'
 //   3. define: explicit name=value pairs from the task config.
 //   4. binPaths prepended to PATH (after all the above resolve PATH).
 
-/**
- * Exported so the schema doc's enumeration of it can be PINNED against the
- * real list: a hand-copied allowlist is how the two drift, and a reader
- * asking "what does my build script actually see?" is asking a
- * security-shaped question that a stale list answers wrongly.
- */
-export const ESSENTIAL_ENV: readonly string[] = [
-  'PATH',
-  'HOME',
-  'SHELL',
-  'USER',
-  'LOGNAME',
-  'TMPDIR',
-  'TEMP',
-  'TMP',
-  'LANG',
-  'LC_ALL',
-  'LC_CTYPE',
-  'TERM',
-  'COLORTERM',
-  'FORCE_COLOR',
-  'NO_COLOR',
-  'CI',
-  'NODE_OPTIONS',
-  // Where corepack and pnpm keep their own binaries, as HOME is: a machine
-  // path, never task output. Without them a corepack shim re-downloads its
-  // manager (offline or sandboxed: fails) and pnpm loses its global dir.
-  'COREPACK_HOME',
-  'PNPM_HOME',
-]
-
 /**
  * The two variables vx sets on every task it spawns, over the layers
  * above: the workspace root the run is in and the `project#task` running.

package/src/exec/executor.ts

@@ -73,12 +73,8 @@ export interface TaskInputs {
     readonly hash: string
     readonly outputs: readonly string[]
   }>
-  /** Digest of the project's own `package.json` (folded even when no glob lists it). */
-  readonly packageJsonDigest: string
   /** Digest of the resolved task config. */
   readonly configDigest: string
-  /** The workspace fingerprint (root manifests + lockfile). */
-  readonly workspaceFingerprint: string
 }
 
 export interface ExecuteRequest {
@@ -146,7 +142,7 @@ export interface ExecuteRequest {
    * work and returns: a child an executor spawned is not one core can
    * reach (H-10, H-12). One already aborted is work not to start (B-55).
    * Any exit after the timeout's abort, a 0 included, is a timeout. Core
-   * waits the kill grace (`VX_KILL_GRACE_MS`, 2 s) after the abort, then
+   * waits the kill grace (`VX_RUN_KILL_GRACE`, 2 s) after the abort, then
    * settles the attempt without `execute` and abandons it (H-14).
    */
   readonly signal?: AbortSignal

package/src/exec/kill-tree.ts

@@ -11,7 +11,7 @@
 // takes even that.
 
 import { closeSync, readdirSync, readFileSync, writeSync } from 'node:fs'
-import { procfsIsOwn, taskShell } from '../util/index.js'
+import { helperEnv, procfsIsOwn, taskShell } from '../util/index.js'
 
 export type Child = ReturnType<typeof Bun.spawn>
 
@@ -104,6 +104,7 @@ function startGuard(): void {
   try {
     const guard = Bun.spawn([taskShell(), '-c', GUARD_SCRIPT], {
       argv0: 'vx-group-guard',
+      env: helperEnv(),
       stdio: ['ignore', 'ignore', 'ignore', 'pipe'],
       // Out of vx's group, so a Ctrl-C at the terminal leaves it to the
       // pipe; vx's own teardown owns that path.

package/src/exec/sandbox-runtime.ts

@@ -62,6 +62,7 @@ import {
 import {
   BUN_GLOB_WILDCARDS,
   executablePath,
+  helperEnv,
   taskShell,
   grantPrefix,
   isTmpdirRefusal,
@@ -1806,10 +1807,11 @@ function spawnHostBridges(ports: readonly number[], tag: string): void {
             ? Bun.spawn(argv, {
                 stdio: ['ignore', 'ignore', 'ignore'],
                 detached: true,
+                env: helperEnv(),
               })
             : Bun.spawn(
                 [taskShell(), '-c', `${guardLine(3)}exec ${argv.map(shellQuote).join(' ')}`],
-                { stdio: ['ignore', 'ignore', 'ignore', guard], detached: true },
+                { stdio: ['ignore', 'ignore', 'ignore', guard], detached: true, env: helperEnv() },
               ),
         ),
       )
@@ -2691,6 +2693,15 @@ function expandGrants(
       // names a wall literally never reaches this loop and stays, and one
       // spelled with escaped brackets names it as surely.
       if (namedPath(p) === undefined && walls.some((w) => atOrUnder(real, w))) continue
+      // A write hit that HOLDS a wall would bind it writable: `.*` in a root
+      // project matched `.vx`, which holds the cache. A read hit is punched
+      // around it instead (`punchWalls`).
+      if (
+        unmatched !== undefined &&
+        namedPath(p) === undefined &&
+        walls.some((w) => atOrUnder(w, real))
+      )
+        continue
       out.push(abs)
       hits++
     }

package/src/exec/sandbox-violations.ts

@@ -744,6 +744,9 @@ export function refusedConnections(records: readonly string[]): SandboxViolation
   }))
 }
 
+/** Write syscalls that act on a path's last component, not what a link there names. */
+const NAME_SYSCALL = /^(?:symlink|unlink|rename|rmdir|mknod|link)/
+
 /**
  * The writes SRT's Linux observer saw that this task's binds do not cover.
  * The observer reports every write-intent syscall as `deny <syscall>
@@ -774,7 +777,12 @@ export function refusedWrites(
     // `5>out.log` in the project reported a write to `out.log` and failed
     // a clean task (2026-10-02).
     if (/^\/(?:dev|proc)\//.test(raw)) continue
-    const abs = toRealPath(raw)
+    // These act on the name itself, never through it: resolving the link
+    // `ln -s ../src/a.ts dist/a` just made judged the write by `src/a.ts`,
+    // and a clean task failed with a fix that granted `write: ['src/']`.
+    const abs = NAME_SYSCALL.test(syscall)
+      ? path.join(toRealPath(path.dirname(raw)), path.basename(raw))
+      : toRealPath(raw)
     if (isUnderAny(abs, binds) || underGlob(abs, globs)) continue
     // A directory a write bind lies in exists, since bwrap made it to mount
     // the bind: `mkdir -p node_modules/.cache/tool` under a grant of

package/src/graph/dependency-spec.ts

@@ -11,7 +11,7 @@ export type DependencySpec =
 
 export class DependencySpecError extends Error {
   constructor(raw: string, message: string) {
-    super(`Invalid dependency spec "${raw}": ${message}`)
+    super(`invalid dependsOn "${raw}": ${message}`)
   }
 }
 

package/src/graph/index.ts

@@ -24,6 +24,7 @@ export {
   declaredTask,
   excludeDependencies,
   expandRequested,
+  type GraphRules,
   isGroupTask,
   markSurfacedDeps,
   outputsOverlap,

package/src/graph/priorities.ts

@@ -161,7 +161,7 @@ export function computeReverseDepCount(nodes: Map<string, TaskNode>): Map<string
 
 /**
  * The ready-queue baseline a workspace may pick in place of the default
- * (`schedule` in vx.workspace.ts). Each ranks with no timings; a `schedule`
+ * (`schedule` in .vx/workspace.ts). Each ranks with no timings; a `schedule`
  * plugin's weights still sort above it, and it breaks their ties.
  *   - `most-work`: transitive dependents (`computeReverseDepCount`), the default.
  *   - `critical-path`: steps on the longest chain of dependents below a task.

package/src/graph/scheduler.ts

@@ -121,14 +121,14 @@ export interface TaskOutcome {
   groupUpstream?: readonly TaskOutcome[]
   /**
    * This task RAN over inputs its key no longer describes: one moved while
-   * it ran, the workspace fingerprint moved, or an upstream carried this
+   * it ran, a claimed root file moved, or an upstream carried this
    * mark. Its save was withheld, and its outputs are not what `hash` names,
    * so a dependant that folds `hash` saves nothing either (A-12).
    */
   unkeyed?: true
   /**
    * The run's cache policy read and wrote nothing (`--no-cache`,
-   * `--cache=local:`): no cache answered for this task, so a run of it is
+   * `--cache-policy=local:`): no cache answered for this task, so a run of it is
    * `no-cache`, not a miss. Set by `run()`; `ranNoCache` reads it.
    */
   cacheOff?: true
@@ -158,11 +158,17 @@ export interface TaskOutcome {
    * the spawn itself failed. Every label reads this instead of the exit.
    */
   notReady?: 'timeout' | 'exited' | 'spawn'
+  /**
+   * The input that changed while the command ran, failing the task under
+   * `inputStability.severity: 'error'` (workspace-relative; '' when vx
+   * could not name it). The exit is vx's 1; the label reads this instead.
+   */
+  inputMoved?: string
   /** Executor-reported placement label (`ExecuteResult.where`) — set only
    *  when the task ran somewhere other than this host. Telemetry-only. */
   where?: string
   /** `'deferred'` when the task's outputs were left in the remote store
-   *  (`--download=none`) instead of landing on this machine. Absent for
+   *  (`--cache-download=none`) instead of landing on this machine. Absent for
    *  every ordinary outcome. Telemetry-only. */
   outputs?: 'deferred'
   /**
@@ -183,7 +189,7 @@ export interface TaskOutcome {
   restored?: boolean
   /**
    * How many times the task executed this run, when `exec.retries` /
-   * `--retry` re-ran failed attempts. Set only when > 1 — a plain
+   * `--retries` re-ran failed attempts. Set only when > 1 — a plain
    * single-attempt run carries nothing. Not persisted; telemetry-side
    * flaky detection reads it off the outcome stream.
    */
@@ -216,6 +222,12 @@ export interface TaskOutcome {
     systemInfo?: string[]
     /** Credential paths denied and left out of the grants: an agent applies the fix as given. */
     withheld?: string[]
+    /**
+     * Reads of the project the task's `cache.inputs.files` does not match:
+     * add them there too when the output depends on them, or a hit replays
+     * output built from an older copy. Cached tasks only.
+     */
+    inputs?: string[]
   }
 }
 
@@ -267,7 +279,7 @@ export interface ScheduleOptions {
    * outcome lands. Absent = stderr. The run gives it the task's own
    * stderr, so its frame carries the reason.
    */
-  onError?: (node: TaskNode, line: string) => void
+  onError?: (node: TaskNode, line: string, err: unknown) => void
   /**
    * What an outcome still owes before its dependents may start — a cache
    * save that runs off the execution slot (the orchestrator's save lane):
@@ -294,7 +306,7 @@ export interface ScheduleOptions {
    */
   priorities?: ReadonlyMap<string, number>
   /**
-   * The baseline ranking under `priorities` (`schedule` in vx.workspace.ts).
+   * The baseline ranking under `priorities` (`schedule` in .vx/workspace.ts).
    * Undefined or `most-work` is the reverse-deps count above.
    */
   strategy?: ScheduleStrategy
@@ -1027,7 +1039,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
             }
             try {
               if (options.onError === undefined) process.stderr.write(line)
-              else options.onError(node, line)
+              else options.onError(node, line, err)
             } catch {
               process.stderr.write(line)
             }

package/src/graph/task-graph.ts

@@ -288,10 +288,16 @@ export interface BuildGraphOptions {
    * with other root-anchored ones.
    */
   workspaceRoot?: string
-  /** The workspace's `rules`; each is on unless set to `false`. */
-  rules?: WorkspaceRules | undefined
+  /** The workspace's `run.rules`; each is on unless set to `false`. */
+  rules?: GraphRules | undefined
 }
 
+/**
+ * `run.rules` as the graph applies them. `locked`: a run, which never
+ * checks them; `vx lock` and `vx lock --check` do (owner, 2026-10-14).
+ */
+export type GraphRules = WorkspaceRules & { readonly locked?: boolean }
+
 /**
  * The refusal of a literal `^name` that no project in the workspace
  * declares: it has no holder anywhere, so it can only be a typo (nx#32779
@@ -301,7 +307,7 @@ export interface BuildGraphOptions {
  */
 export function undeclaredDepsError(taskId: string, name: string): UserError {
   return new UserError(
-    `Task ${taskId} depends on ^${name} but no project in the workspace declares ${name}`,
+    `${taskId}: dependsOn ^${name} but no project in the workspace declares ${name}`,
     'VX_E_DEPENDS_ON',
   )
 }
@@ -493,7 +499,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       spec = parseDependencySpec(raw)
     } catch (err) {
       if (err instanceof DependencySpecError) {
-        throw new UserError(`Task ${id}: ${err.message}`, 'VX_E_DEPENDS_ON')
+        throw new UserError(`${id}: ${err.message}`, 'VX_E_DEPENDS_ON')
       }
       throw err
     }
@@ -505,19 +511,19 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
     // they name a namespace of tasks to add (Nx 19.5 parity).
     if (spec.kind === 'wildcardSelf' || spec.kind === 'wildcardDeps') {
       throw new UserError(
-        `Task ${id}: dependsOn does not accept bare wildcards (got "${raw}")`,
+        `${id}: dependsOn does not accept bare wildcards (got "${raw}")`,
         'VX_E_DEPENDS_ON',
       )
     }
     if (spec.negated) {
       throw new UserError(
-        `Task ${id}: dependsOn does not accept negation (got "${raw}")`,
+        `${id}: dependsOn does not accept negation (got "${raw}")`,
         'VX_E_DEPENDS_ON',
       )
     }
     if (spec.kind === 'cross' && (isTaskPattern(spec.task) || isTaskPattern(spec.project))) {
       throw new UserError(
-        `Task ${id}: dependsOn patterns are not supported in the "pkg#task" form (got "${raw}")`,
+        `${id}: dependsOn patterns are not supported in the "pkg#task" form (got "${raw}")`,
         'VX_E_DEPENDS_ON',
       )
     }
@@ -537,7 +543,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
         // doesn't resolve in this project.
         if (!visit(frame, projectName, spec.task, false)) {
           throw new UserError(
-            `Task ${id} depends on ${taskId(projectName, spec.task)} but no such task is declared`,
+            `${id}: dependsOn ${taskId(projectName, spec.task)} but no such task is declared`,
             'VX_E_DEPENDS_ON',
           )
         }
@@ -570,6 +576,17 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       // last (`resolveDeferred`), and a walk that meets it on a cycle takes
       // the edge and goes on past it, so the builds it could not depend on
       // still come first.
+      //
+      // With no edge source every `^` resolves to nothing and its upstream
+      // folds into no key: a stale hit, green. With one, a project with no
+      // deps is a leaf. The default `build`'s `^build` is no exception: a
+      // task behind it would fold no upstream either.
+      if (!packageGraph.edgeSource) {
+        throw new UserError(
+          `${id}: ^${spec.task} needs project edges; add pnpm()/bun()/npm()/yarn() or a plugin that returns \`deps\``,
+          'VX_E_DEPENDS_ON',
+        )
+      }
       const visited = new Set<string>([projectName])
       if (!isTaskPattern(spec.task)) {
         const held = walkHolders(frame, spec.task, visited, projectName)
@@ -602,11 +619,11 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
         // The loader spells `//` as the root project's name when there is one.
         if (spec.project === '//')
           throw new UserError(
-            `Task ${id} depends on //#${spec.task}, Turbo's root package, but the workspace root is no project here: give it a package.json name and a vx.config with that task`,
+            `${id}: dependsOn //#${spec.task}, the workspace root's task, but the root declares no such task: add a vx.config at the root declaring it and run \`vx lock\``,
             'VX_E_DEPENDS_ON',
           )
         throw new UserError(
-          `Task ${id} depends on ${taskId(spec.project, spec.task)} but no such project or task is declared`,
+          `${id}: dependsOn ${taskId(spec.project, spec.task)} but no such project or task is declared`,
           'VX_E_DEPENDS_ON',
         )
       }
@@ -746,7 +763,7 @@ function reachingTo(nodes: Map<string, TaskNode>, target: string): Set<string> {
 export function checkGraph(
   nodes: Map<string, TaskNode>,
   workspaceRoot?: string,
-  rules?: WorkspaceRules,
+  rules?: GraphRules,
 ): void {
   for (const [key, node] of nodes) {
     if (node.id !== key) {
@@ -762,8 +779,12 @@ export function checkGraph(
   }
   for (const node of nodes.values()) refuseSelfClean(node)
   detectCycle(nodes)
-  detectOutputCollisions(nodes, workspaceRoot, rules?.exclusiveOutputs !== false)
-  if (rules?.upfrontKeys !== false) detectInputOverlaps(nodes, workspaceRoot)
+  const exclusive = rules?.exclusiveOutputs !== false
+  const locked = rules?.locked === true
+  // Under a lock an exclusive graph has no overlap to mark; a non-exclusive
+  // one still needs the addition marks the walk derives.
+  if (!locked || !exclusive) detectOutputCollisions(nodes, workspaceRoot, exclusive)
+  if (rules?.upfrontKeys !== false && !locked) detectInputOverlaps(nodes, workspaceRoot)
 }
 
 /**
@@ -1352,13 +1373,13 @@ function neverWritesLocally(n: TaskNode): boolean {
 }
 
 /**
- * The way out of an edge-ordered overlap under `rules.exclusiveOutputs`: an
+ * The way out of an edge-ordered overlap under `run.rules.exclusiveOutputs`: an
  * ordered pair is correct (the addition shape, item 588), only slower to
  * clean and restore, so the rule may be turned off.
  */
 const EXCLUSIVE_OUTPUTS_FIX =
-  'Give each task its own output path, or set rules: { exclusiveOutputs: false } in ' +
-  "vx.workspace.ts to let a dependant add to its upstream's outputs."
+  'Give each task its own output path, or set run.rules.exclusiveOutputs: false in ' +
+  ".vx/workspace.ts to let a dependant add to its upstream's outputs."
 
 function collide(
   a: TaskNode,
@@ -1383,7 +1404,7 @@ function collide(
       // dependant runs after its upstream and adds to that tree, so the
       // order is fixed and the dependant's own set can be told apart from
       // what it found. Marked on both, and the pair is allowed when
-      // `rules.exclusiveOutputs` is off (X-53). Without an edge the two run
+      // `run.rules.exclusiveOutputs` is off (X-53). Without an edge the two run
       // in either order, and the refusal below stands.
       const [up, down] = reaches(b.id, a.id) ? [a, b] : reaches(a.id, b.id) ? [b, a] : []
       if (up !== undefined && exclusive)
@@ -1504,7 +1525,7 @@ interface Side {
 }
 
 /**
- * `rules.upfrontKeys` (X-54): refuse a task whose input globs can match
+ * `run.rules.upfrontKeys` (X-54): refuse a task whose input globs can match
  * another task's declared outputs. Such a key reads bytes a producer writes
  * this run, so it is not known until the producer ran (`stable-keys.ts`
  * keeps it waiting); refused, every key reads only what no task writes and
@@ -1677,7 +1698,7 @@ function readsOutputs(
           `${writer.node.id}'s output ${JSON.stringify(shown)} — a task's key must not read ` +
           `another task's outputs (the dependency's key already cascades through dependsOn). ` +
           `Exclude it: add ${JSON.stringify(`!${out}`)} to ${reader.node.id}'s ` +
-          `cache.inputs.${field}, or set rules: { upfrontKeys: false } in vx.workspace.ts to ` +
+          `cache.inputs.${field}, or set run.rules.upfrontKeys: false in .vx/workspace.ts to ` +
           `let it wait for its producer.`,
         'VX_E_INPUT_IS_OUTPUT',
       )
@@ -1725,7 +1746,10 @@ function detectCycle(nodes: Map<string, TaskNode>): void {
           for (let i = 0; i < stack.length; i += 2) path.push(idsArr[stack[i]!]!)
           const startInPath = path.indexOf(idsArr[depIdx]!)
           const cycle = [...path.slice(startInPath), idsArr[depIdx]!].join(' -> ')
-          throw new UserError(`Cycle detected in task graph: ${cycle}`, 'VX_E_CYCLE')
+          throw new UserError(
+            `dependsOn cycle: ${cycle} — remove one edge of the loop`,
+            'VX_E_CYCLE',
+          )
         }
         color[depIdx] = GRAY
         stack.push(depIdx, 0)

package/src/handoff.ts

@@ -0,0 +1,169 @@
+// A global vx hands off to the project's own (owner, 2026-10-13), found
+// from the workspace root, the one lookup every verb shares. Here for
+// the compiled binary installed by hand; an npm install's launcher
+// (npm-launcher.sh) walks the same way and `exec`s, which Bun cannot. The
+// walk runs before anything else loads, through `Bun.file(…).exists()`:
+// importing `node:fs` alone was ~1.1 ms of a 4 ms start (2026-10-13).
+
+/**
+ * The project-local vx to run instead of this one, or null: the workspace
+ * root's ({@link workspaceFile}) `node_modules/@vzn/vx`, run through its
+ * `.bin/vx`. Null once handed
+ * off (one hop), for a vx that is not a standalone compiled binary (source;
+ * an npm install, whose launcher already walked), outside a workspace,
+ * when the local one is this binary, and when another user owns it.
+ */
+export async function localVx(
+  cwd: string,
+  execPath: string,
+  compiled: boolean,
+  uid = process.getuid?.(),
+): Promise<string | null> {
+  if (process.env['VX_HANDED_OFF'] !== undefined || !compiled) return null
+  if (execPath.includes('/node_modules/')) return null
+  const file = await workspaceFile(cwd)
+  if (file === null) return null
+  const root = workspaceRootOf(file)
+  if (!(await Bun.file(`${root}/node_modules/@vzn/vx/package.json`).exists())) return null
+  const bin = `${root}/node_modules/.bin/vx`
+  const { realpathSync, statSync } = await import('node:fs')
+  try {
+    const real = realpathSync(bin)
+    // One another user planted would run as you.
+    if (statSync(real).uid !== uid) return null
+    return real === realpathSync(execPath) ? null : bin
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The workspace config's paths under the root, in lookup order: one marks
+ * the workspace root, the directory holding its `.vx` (owner, 2026-10-14).
+ */
+export const WORKSPACE_CONFIG_FILENAMES = [
+  '.vx/workspace.ts',
+  '.vx/workspace.mts',
+  '.vx/workspace.js',
+  '.vx/workspace.mjs',
+  // A CommonJS config (`module.exports = …`), as Vite and TS name theirs: it
+  // was ignored without a word (D-86).
+  '.vx/workspace.cts',
+  '.vx/workspace.cjs',
+]
+
+/** The workspace root a workspace config marks: the directory above its `.vx`. */
+export function workspaceRootOf(file: string): string {
+  return file.slice(0, file.lastIndexOf('/.vx/')) || '/'
+}
+
+const files = new Map<string, Promise<string | null>>()
+
+/**
+ * The workspace config that marks the root for `dir`: the first
+ * `.vx/workspace.*` from `dir` up to the git top-level ({@link gitTop}),
+ * inclusive, or to `/` outside git (owner, 2026-10-13: "Workspace file is
+ * the ultimate" and "never go out of git root"). Null when there is none.
+ * Learned once per directory per run: the hand-off and the workspace root
+ * share it (principle 9).
+ */
+export function workspaceFile(dir: string): Promise<string | null> {
+  let file = files.get(dir)
+  if (file === undefined) {
+    file = findWorkspaceFile(dir)
+    files.set(dir, file)
+  }
+  return file
+}
+
+/** vx wrote a workspace config (`vx init`): what was learned before it is stale. */
+export function workspaceFileWritten(): void {
+  files.clear()
+}
+
+async function findWorkspaceFile(start: string): Promise<string | null> {
+  const top = await gitTop(start)
+  const passed: string[] = []
+  let found: string | null = null
+  walk: for (let d = start; ; d = d.slice(0, d.lastIndexOf('/'))) {
+    passed.push(d || '/')
+    for (const name of WORKSPACE_CONFIG_FILENAMES) {
+      const file = `${d}/${name}`
+      if (await Bun.file(file).exists()) {
+        found = file
+        break walk
+      }
+    }
+    if (d === '' || d === top) break
+  }
+  // Every directory walked has the same answer: the loader asks for the root's.
+  for (const d of passed) if (!files.has(d)) files.set(d, Promise.resolve(found))
+  return found
+}
+
+const tops = new Map<string, Promise<string | null>>()
+
+/**
+ * The git top-level holding `dir`, or null outside git: the nearest `.git`
+ * up from it, a directory in a clone, a file in a worktree. A submodule's
+ * `.git` file points into its superproject's `.git/modules`, so the walk
+ * goes on to the superproject's. Learned once per directory per run: the
+ * hand-off and the workspace root walk share it (principle 9).
+ */
+export function gitTop(dir: string): Promise<string | null> {
+  let top = tops.get(dir)
+  if (top === undefined) {
+    top = findGitTop(dir)
+    tops.set(dir, top)
+  }
+  return top
+}
+
+async function findGitTop(start: string): Promise<string | null> {
+  for (let d = start; ; d = d.slice(0, d.lastIndexOf('/'))) {
+    // A file each: `exists()` is false for a directory.
+    if (await Bun.file(`${d}/.git/HEAD`).exists()) return d || '/'
+    const file = Bun.file(`${d}/.git`)
+    if (await file.exists()) {
+      const gitdir = await file.text().catch(() => '')
+      if (!/(^|[\s/])\.git\/modules\//.test(gitdir)) return d || '/'
+    }
+    if (d === '') return null
+  }
+}
+
+/** This vx's own file: the compiled binary, else the source entry Bun runs. */
+export function vxPath(): string {
+  return Bun.main.startsWith('/$bunfs') ? process.execPath : Bun.main
+}
+
+/**
+ * Run `bin` with this process's arguments and stdio, and exit as it does.
+ * A signal sent to this vx alone (`kill`, a process manager) is passed on;
+ * one the terminal sent reached the whole foreground group already, and a
+ * second would read as "stop now" (npm-launcher.cjs, the same rule).
+ */
+export async function handOff(bin: string, args: readonly string[]): Promise<never> {
+  const child = Bun.spawn([bin, ...args], {
+    stdio: ['inherit', 'inherit', 'inherit'],
+    env: { ...process.env, VX_HANDED_OFF: process.execPath },
+  })
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const) {
+    process.on(sig, () => {
+      if (!inForeground()) child.kill(sig)
+    })
+  }
+  const code = await child.exited
+  const { constants } = await import('node:os')
+  process.exit(child.signalCode === null ? code : 128 + (constants.signals[child.signalCode] ?? 1))
+}
+
+function inForeground(): boolean {
+  try {
+    const stat = Bun.spawnSync(['ps', '-o', 'pgid=,tpgid=', '-p', String(process.pid)])
+    const [pgid, tpgid] = stat.stdout.toString().trim().split(/\s+/)
+    return pgid !== undefined && pgid === tpgid
+  } catch {
+    return false
+  }
+}