@vzn/vx 0.0.636 → 0.0.638

package/src/settings.ts

@@ -0,0 +1,428 @@
+// Every vx setting, once: its path is its `.vx/workspace` key, and its
+// environment variable and flag are derived from that path. Parsing,
+// validation, `vx info`'s settings view and the docs' settings tables all
+// read this list (`tests/settings.test.ts` holds src and docs to it).
+
+import {
+  machineParallelism,
+  MAX_TIMEOUT_MS,
+  parseDecimalInt,
+  parseDuration,
+  parseSize,
+  UserError,
+} from './util/index.js'
+
+export type SettingKind =
+  | { readonly type: 'int'; readonly min: number }
+  | { readonly type: 'concurrency' }
+  // `zero`: 0 is a value ("wait for nothing not already done"), not a typo.
+  | { readonly type: 'duration'; readonly timer?: true; readonly zero?: true }
+  | { readonly type: 'size' }
+  | { readonly type: 'bool' }
+  | { readonly type: 'enum'; readonly values: readonly string[] }
+  | { readonly type: 'string' }
+
+export interface Setting {
+  /** The `.vx/workspace` path (`run.timeout`); env and flag derive from it. */
+  readonly path: string
+  readonly kind: SettingKind
+  /** The built-in, as the docs print it. */
+  readonly default: string
+  /** One line for the docs table. */
+  readonly doc: string
+  /** The verb whose flag sets it (`vx run --timeout`); none → env and config only. */
+  readonly flag?: { readonly verb: 'run' | 'watch'; readonly name: string }
+  /** The task field that overrides it, and beats every run-level source. */
+  readonly task?: string
+  /** False: read before `.vx/workspace` loads, so flag and env only. */
+  readonly config?: false
+  /** False: `.vx/workspace` only, no variable. */
+  readonly env?: false
+}
+
+const SCHEDULES = ['most-work', 'critical-path', 'direct-dependents', 'ready-order'] as const
+
+export const SETTINGS: readonly Setting[] = [
+  {
+    path: 'run.concurrency',
+    kind: { type: 'concurrency' },
+    default: 'the cores this process may use',
+    doc: "Tasks at once: a positive integer, or a share of the cores (`'50%'`).",
+    flag: { verb: 'run', name: '--concurrency' },
+  },
+  {
+    path: 'run.schedule',
+    kind: { type: 'enum', values: SCHEDULES },
+    default: 'most-work',
+    doc: 'Which ready task starts first when there are more than workers.',
+    flag: { verb: 'run', name: '--schedule' },
+  },
+  {
+    path: 'run.affectedBase',
+    kind: { type: 'string' },
+    default: 'origin/HEAD, then the trunk, else HEAD~1',
+    doc: 'The git ref a bare `--affected` compares with.',
+  },
+  {
+    path: 'run.branch',
+    kind: { type: 'string' },
+    default: "git's branch, then the CI provider's",
+    doc: 'The branch a run records in its history and forecasts from. Flag and env only: a committed branch would be wrong on every other branch.',
+    flag: { verb: 'run', name: '--branch' },
+    config: false,
+  },
+  {
+    path: 'run.timeout',
+    kind: { type: 'duration', timer: true },
+    default: 'none',
+    doc: "A task's time limit, for tasks without their own `exec.timeout` (`'30m'`).",
+    flag: { verb: 'run', name: '--timeout' },
+    task: 'exec.timeout',
+  },
+  {
+    path: 'run.retries',
+    kind: { type: 'int', min: 0 },
+    default: '0',
+    doc: 'Re-runs of a failed task, for tasks without their own `exec.retries`.',
+    flag: { verb: 'run', name: '--retries' },
+    task: 'exec.retries',
+  },
+  {
+    path: 'run.continue',
+    kind: { type: 'enum', values: ['never', 'deps-ok', 'always'] },
+    default: 'deps-ok',
+    doc: 'What a failed task takes down: `never` stops the run, `deps-ok` skips its dependents, `always` runs them too.',
+    flag: { verb: 'run', name: '--continue' },
+  },
+  {
+    path: 'run.outputLogs',
+    kind: { type: 'enum', values: ['full', 'errors-only', 'hash-only', 'none'] },
+    default: '`full` on CI, else by what the run selects',
+    doc: 'Which task output the run prints. Chosen before the workspace loads, so flag and env only.',
+    flag: { verb: 'run', name: '--output-logs' },
+    config: false,
+  },
+  {
+    path: 'run.killGrace',
+    kind: { type: 'duration', timer: true },
+    default: '2s',
+    doc: 'How long a task that ignores SIGTERM gets before SIGKILL.',
+    flag: { verb: 'run', name: '--kill-grace' },
+  },
+  {
+    path: 'run.teardownTimeout',
+    kind: { type: 'duration', timer: true, zero: true },
+    default: '3s',
+    doc: "The bound on each plugin's end-of-run flush and teardown.",
+    flag: { verb: 'run', name: '--teardown-timeout' },
+  },
+  {
+    path: 'run.readyNotice',
+    kind: { type: 'duration', timer: true },
+    default: '10s',
+    doc: 'How long a persistent task may take to match `readyWhen` before vx says it waits.',
+    flag: { verb: 'run', name: '--ready-notice' },
+  },
+  {
+    path: 'run.rules.exclusiveOutputs',
+    kind: { type: 'bool' },
+    default: 'true',
+    doc: 'Refuse two tasks whose outputs overlap even when an edge orders them.',
+  },
+  {
+    path: 'run.rules.upfrontKeys',
+    kind: { type: 'bool' },
+    default: 'true',
+    doc: "Refuse a task whose inputs can match another task's outputs.",
+  },
+  {
+    path: 'cache.dir',
+    kind: { type: 'string' },
+    default: '.vx/cache, entries in ~/.vx/<repo>/cache',
+    doc: 'Where the cache lives, relative to the workspace root; named, it holds the whole cache.',
+    flag: { verb: 'run', name: '--cache-dir' },
+  },
+  {
+    path: 'cache.retention.maxSize',
+    kind: { type: 'size' },
+    default: 'none',
+    doc: "Evict least-recently-used entries at each run's end until the cache is under this (`'10GB'`).",
+  },
+  {
+    path: 'cache.retention.olderThan',
+    kind: { type: 'duration' },
+    default: 'none',
+    doc: "Evict entries unused for this long at each run's end (`'30d'`).",
+  },
+  {
+    path: 'cache.policy',
+    kind: { type: 'string' },
+    default: 'every layer reads and writes',
+    doc: "Which layers a run reads and writes (`'local:rw,remote:r'`); `--no-cache` and `--force` apply on top.",
+    flag: { verb: 'run', name: '--cache-policy' },
+  },
+  {
+    path: 'cache.scope',
+    kind: { type: 'string' },
+    default: 'none (the default keys)',
+    doc: "Where cache writes land (`'pr-123'`): reads try the default key, then the scope's.",
+    flag: { verb: 'run', name: '--cache-scope' },
+  },
+  {
+    path: 'cache.download',
+    kind: { type: 'enum', values: ['all', 'toplevel', 'none'] },
+    default: 'all',
+    doc: 'Which remote hits land on disk: every one, only the requested tasks, or none.',
+    flag: { verb: 'run', name: '--cache-download' },
+  },
+  {
+    path: 'cache.inputStability.strategy',
+    kind: { type: 'enum', values: ['immutable', 'mutable', 'unchecked'] },
+    default: 'immutable',
+    doc: 'What a write to an input during the command means for the save, for tasks without their own.',
+    task: 'cache.inputStability.strategy',
+  },
+  {
+    path: 'cache.inputStability.severity',
+    kind: { type: 'enum', values: ['warn', 'error'] },
+    default: 'warn',
+    doc: 'Whether a skipped save warns or fails the task, for tasks without their own.',
+    task: 'cache.inputStability.severity',
+  },
+  {
+    path: 'cache.outputs.clean',
+    kind: { type: 'bool' },
+    default: 'true',
+    doc: "Remove a task's declared outputs before it runs on a miss, for tasks without their own.",
+    task: 'cache.outputs.clean',
+    env: false,
+  },
+  {
+    path: 'lock.reviewFiles',
+    kind: { type: 'bool' },
+    default: 'true',
+    doc: "`vx lock` writes each project's resolved config, pretty, to `vx.lock.json` beside its `vx.config`, for review; vx never reads it.",
+  },
+  {
+    path: 'watch.poll',
+    kind: { type: 'bool' },
+    default: 'false',
+    doc: 'Poll for changes from the start instead of the OS watcher.',
+    flag: { verb: 'watch', name: '--poll' },
+  },
+  {
+    path: 'config.workerTimeout',
+    kind: { type: 'duration', timer: true },
+    default: '30s',
+    doc: 'How long one config evaluation may take.',
+    config: false,
+  },
+  {
+    path: 'debug.timing',
+    kind: { type: 'bool' },
+    default: 'false',
+    doc: "Print the run's stage timings to stderr.",
+    config: false,
+  },
+  {
+    path: 'debug.watch',
+    kind: { type: 'bool' },
+    default: 'false',
+    doc: '`vx watch`: say on stderr each time the loop arms, with the projects it watches.',
+    config: false,
+  },
+  {
+    path: 'debug.dumpable',
+    kind: { type: 'bool' },
+    default: 'false',
+    doc: 'Linux: keep vx dumpable, so strace or a debugger can read its memory and `/proc/<pid>/fd`, and an unsandboxed task its env.',
+    config: false,
+  },
+]
+
+/** The `.vx/workspace` groups that hold settings; `plugins` is the other key. */
+export const SETTING_GROUPS = ['run', 'cache', 'lock', 'watch'] as const
+
+const BY_PATH = new Map(SETTINGS.map((s) => [s.path, s]))
+
+export function setting(path: string): Setting {
+  return BY_PATH.get(path)!
+}
+
+/** `run.killGrace` → `VX_RUN_KILL_GRACE`. */
+export function envName(path: string): string {
+  return `VX_${path
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/\./g, '_')
+    .toUpperCase()}`
+}
+
+/** What a value of this kind looks like, for an error. */
+export function kindHint(kind: SettingKind): string {
+  switch (kind.type) {
+    case 'int':
+      return kind.min === 0 ? 'a non-negative integer' : `an integer ≥ ${kind.min}`
+    case 'concurrency':
+      return "a positive integer, or a share of the cores like '50%'"
+    case 'duration':
+      // A timer past 2^31-1 ms fires at once, so "no limit" is no value.
+      return kind.timer === true
+        ? "a duration like '500ms', '30s' or '5m', at most 24 days"
+        : "a duration like '45s', '12h' or '30d'"
+    case 'size':
+      return "a size like '500MB' or '10GB'"
+    case 'bool':
+      return 'true or false'
+    case 'enum':
+      return `one of ${kind.values.map((v) => `'${v}'`).join(', ')}`
+    case 'string':
+      return 'a non-blank string'
+  }
+}
+
+/**
+ * A positive decimal integer, or `<n>%` of the cores this process may use
+ * (`50%` on eight cores is 4, never below 1; over 100% is allowed for
+ * I/O-bound work; a container's CPU quota caps the count the way it caps
+ * the default), resolved here so the run sees one number and the summary
+ * says what it ran with.
+ */
+export function parseConcurrency(v: unknown, cpus = machineParallelism()): number | null {
+  if (typeof v !== 'string') return null
+  const pct = /^(\d+)%$/.exec(v)
+  if (pct) {
+    const n = parseDecimalInt(pct[1]!)
+    if (n === null || n < 1) return null
+    return Math.max(1, Math.round((Math.max(1, cpus) * n) / 100))
+  }
+  const n = parseDecimalInt(v)
+  return n === null || n < 1 ? null : n
+}
+
+/**
+ * A setting's value, or null when `raw` is not one. Durations come back in
+ * ms, sizes in bytes and a share of the cores as a count; the rest as typed.
+ */
+export function parseSettingValue(kind: SettingKind, raw: unknown): unknown {
+  switch (kind.type) {
+    case 'int': {
+      const n =
+        typeof raw === 'number' ? raw : typeof raw === 'string' ? parseDecimalInt(raw) : null
+      return n !== null && Number.isSafeInteger(n) && n >= kind.min ? n : null
+    }
+    case 'concurrency':
+      return parseConcurrency(typeof raw === 'number' ? String(raw) : raw)
+    case 'duration': {
+      const n = typeof raw === 'string' ? parseDuration(raw) : null
+      if (n === null || (n === 0 && kind.zero !== true)) return null
+      return kind.timer === true && n > MAX_TIMEOUT_MS ? null : n
+    }
+    case 'size':
+      return typeof raw === 'string' ? parseSize(raw) : null
+    case 'bool':
+      if (typeof raw === 'boolean') return raw
+      return raw === 'true' || raw === '1' ? true : raw === 'false' || raw === '0' ? false : null
+    case 'enum':
+      return typeof raw === 'string' && kind.values.includes(raw) ? raw : null
+    case 'string':
+      return typeof raw === 'string' && raw.trim() !== '' ? raw : null
+  }
+}
+
+/**
+ * Why `raw` from `where` (a variable, a flag, a config field) is refused
+ * for the setting at `path`; `got` is `raw` as the message quotes it. A
+ * bare number for a duration names the unit it lacks, and a timer past the
+ * platform's range says it would fire at once rather than never.
+ */
+export function settingRefusal(
+  path: string,
+  where: string,
+  raw: unknown,
+  got = String(raw),
+): string {
+  const { kind } = setting(path)
+  if (kind.type === 'duration') {
+    const n =
+      typeof raw === 'number'
+        ? raw
+        : typeof raw === 'string' && /^\d+$/.test(raw)
+          ? Number(raw)
+          : null
+    if (n !== null && Number.isSafeInteger(n) && n > 0) {
+      return `${where} takes a duration with its unit, like '${n}ms' or '${Math.max(1, Math.round(n / 1000))}s' (got ${got})`
+    }
+    const ms = typeof raw === 'string' ? parseDuration(raw) : null
+    if (kind.timer === true && ms !== null && ms > MAX_TIMEOUT_MS) {
+      return (
+        `${where} of ${got} exceeds the maximum timer delay (${MAX_TIMEOUT_MS} ms, ~24.8 days): ` +
+        'a longer timer fires at once, it does not mean "no limit"' +
+        (path === 'run.timeout' ? ' — omit it for no limit' : '')
+      )
+    }
+  }
+  return `${where} must be ${kindHint(kind)} (got ${got})`
+}
+
+/** A setting's environment value, parsed; undefined when unset or empty. */
+export function settingEnv(path: string, env: NodeJS.ProcessEnv = process.env): unknown {
+  const { kind, env: read } = setting(path)
+  if (read === false) return undefined
+  const name = envName(path)
+  const raw = env[name]
+  if (raw === undefined || raw === '') return undefined
+  const v = parseSettingValue(kind, raw)
+  if (v === null) throw new UserError(settingRefusal(path, name, raw), 'VX_E_USAGE')
+  return v
+}
+
+/** Validate every set setting variable once, so a deep reader can trust what it reads. */
+export function checkSettingsEnv(env: NodeJS.ProcessEnv = process.env): void {
+  for (const s of SETTINGS) settingEnv(s.path, env)
+}
+
+/** Where a resolved setting came from. */
+export type SettingSource = 'flag' | 'env' | 'workspace' | 'default'
+
+/** `config` at `path` (`run.timeout` → `config.run?.timeout`). */
+export function atPath(config: unknown, path: string): unknown {
+  let v: unknown = config
+  for (const k of path.split('.')) {
+    if (v === null || typeof v !== 'object') return undefined
+    v = (v as Record<string, unknown>)[k]
+  }
+  return v
+}
+
+/**
+ * A run-level setting: the flag's value, else the environment's, else the
+ * workspace's, parsed; undefined with its default. A task override is
+ * applied where the task runs, above all three.
+ */
+export function resolveSetting(
+  path: string,
+  workspace: unknown,
+  flag?: unknown,
+  env: NodeJS.ProcessEnv = process.env,
+): { value: unknown; source: SettingSource } {
+  if (flag !== undefined) return { value: flag, source: 'flag' }
+  const e = settingEnv(path, env)
+  if (e !== undefined) return { value: e, source: 'env' }
+  const w = setting(path).config === false ? undefined : atPath(workspace, path)
+  if (w !== undefined)
+    return { value: parseSettingValue(setting(path).kind, w), source: 'workspace' }
+  return { value: undefined, source: 'default' }
+}
+
+/** `run.rules`, each from its variable, else the workspace; unset ones stay on. */
+export function runRules(workspace: unknown): {
+  exclusiveOutputs?: boolean
+  upfrontKeys?: boolean
+} {
+  const out: { exclusiveOutputs?: boolean; upfrontKeys?: boolean } = {}
+  for (const rule of ['exclusiveOutputs', 'upfrontKeys'] as const) {
+    const { value } = resolveSetting(`run.rules.${rule}`, workspace)
+    if (value !== undefined) out[rule] = value as boolean
+  }
+  return out
+}

package/src/{orchestrator → util}/colors.ts

@@ -13,6 +13,11 @@ const RESET = '\x1b[0m'
 const BOLD = '\x1b[1m'
 const DIM = '\x1b[2m'
 
+// State hues every report shares with the run summary.
+export const SUCCESS = '#22c55e'
+export const WARN = '#eab308'
+export const ERROR = '#ef4444'
+
 export interface ColorSupport {
   enabled: boolean
 }

package/src/util/config-frame.ts

@@ -7,8 +7,9 @@
 import { readFileSync } from 'node:fs'
 import path from 'node:path'
 
-// `<file>: tasks.<path>[:] …`, or a top-level `<file> has unknown field …`.
-const HEAD = /^(\/[^\n]*?\/vx\.config\.[cm]?[jt]s)(?:: (tasks\.[^\s:]+)(:?))? /
+// `<file>: tasks.<path>[:] …`, or a top-level `<file> has unknown field …`,
+// from a project's vx.config or the workspace's .vx/workspace.ts.
+const HEAD = /^(\/[^\n]*?\/(?:vx\.config|\.vx\/workspace)\.[cm]?[jt]s)(?:: (tasks\.[^\s:]+)(:?))? /
 
 /**
  * The message with its file named at `line:col`, relative to `cwd`, and a
@@ -88,3 +89,31 @@ function locate(
 function escapeRe(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
+
+/** A config refusal laid out for `ui.notice`: where, what, the allowed set, the fix, the frame. */
+export interface ConfigRefusal {
+  where: string
+  problem: string
+  allowed?: string
+  fix?: string
+  frame: string
+}
+
+/** `configErrorFrame`'s answer in parts, or undefined when it has none. */
+export function configRefusal(message: string, cwd: string): ConfigRefusal | undefined {
+  const framed = configErrorFrame(message, cwd)
+  if (framed === undefined) return undefined
+  const cut = framed.indexOf('\n\n')
+  const line = framed.slice(0, cut)
+  const frame = framed.slice(cut + 2)
+  const at = /^(\S+?:\d+:\d+):? (.*)$/s.exec(line)
+  if (at === null) return { where: line, problem: '', frame }
+  const said = /^(.*?)(?: \(allowed: ([^)]*)\))?(?: — did you mean ([^?]+)\?)?$/s.exec(at[2]!)!
+  return {
+    where: at[1]!,
+    problem: said[1]!.replace(/^has /, ''),
+    ...(said[2] !== undefined ? { allowed: said[2] } : {}),
+    ...(said[3] !== undefined ? { fix: `use ${said[3]}` } : {}),
+    frame,
+  }
+}

package/src/util/errors.ts

@@ -13,6 +13,8 @@ export class UserError extends Error {
    * does not. `VX_E_REFUSED` is any refusal without a code of its own.
    */
   readonly code: string
+  /** The refusal laid out for a terminal (`refusal`); the message is the same in one line. */
+  parts?: RefusalParts
   // Two signatures, not an optional parameter: the package-api record
   // keeps the one-argument form every plugin already calls.
   constructor(message: string)
@@ -24,9 +26,39 @@ export class UserError extends Error {
   }
 }
 
+/** A refusal in parts, as `ui.notice` draws it: one fact a line, why, and the fix. */
+export interface RefusalParts {
+  /** `info`: nothing is wrong, there is just nothing to show yet. Default `error`. */
+  readonly tone?: 'info'
+  readonly headline: string
+  readonly what?: readonly string[]
+  readonly why?: string
+  readonly fix?: string
+}
+
+/**
+ * A UserError whose terminal form is `parts`. Its message, what JSON and
+ * logs carry, is `message` when given, else the parts in one line.
+ */
+export function refusal(
+  parts: RefusalParts,
+  opts: { code?: string; message?: string } = {},
+): UserError {
+  const message =
+    opts.message ??
+    [
+      [parts.headline, ...(parts.what ?? [])].join(': '),
+      ...(parts.why !== undefined ? [parts.why] : []),
+      ...(parts.fix !== undefined ? [parts.fix] : []),
+    ].join('; ')
+  const err = new UserError(message, opts.code ?? 'VX_E_REFUSED')
+  err.parts = parts
+  return err
+}
+
 // A refusal that opens with the config that caused it: the schema's
 // `<file>: tasks.<name> …` and the loader's `<file> has unknown field …`.
-const CONFIG_REFUSAL = /^\/\S*\/vx\.(?:config|workspace)\.[cm]?[jt]s\b/
+const CONFIG_REFUSAL = /^\/\S*\/(?:vx\.config|\.vx\/workspace)\.[cm]?[jt]s\b/
 
 /**
  * The stable code of anything `bin.ts` catches. A UserError's own, but

package/src/util/essential-env.ts

@@ -0,0 +1,31 @@
+/**
+ * Every task gets these (`exec/env.ts`), so `hideEnvFromTasks` leaves
+ * them. 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',
+]

package/src/util/hide-env.ts

@@ -0,0 +1,107 @@
+import { ESSENTIAL_ENV } from './essential-env.js'
+
+const PR_SET_DUMPABLE = 4
+
+/**
+ * Hide vx's environment from a same-user task. A task gets only declared
+ * variables, but vx itself holds the rest. Not a boundary (`exec.sandbox`
+ * is): it hides the environment, not files. On every verb (owner,
+ * 2026-10-13).
+ *
+ * Linux: make vx non-dumpable, so its `/proc/<pid>/environ` (and ptrace)
+ * close to the task. A child is dumpable again after `exec`, so tasks are
+ * unaffected. Loading `bun:ffi` costs ~0.8 ms. `VX_DEBUG_DUMPABLE` keeps vx
+ * observable: strace cannot read a non-dumpable tracee's memory, nor a
+ * debugger `/proc/<pid>/fd`.
+ *
+ * macOS: `ps eww` reads the env strings the kernel copied above the
+ * stack, and no flag closes that to the same user, so vx zeroes the
+ * values there (owner, 2026-10-13: "Do the override then on macOS").
+ * Bun copied the env at startup, so `process.env`, and every task built
+ * from it, keeps them.
+ */
+export async function hideEnvFromTasks(): Promise<boolean> {
+  if (process.platform === 'darwin') return wipeStartupEnv()
+  if (process.platform !== 'linux' || process.env['VX_DEBUG_DUMPABLE']) return false
+  try {
+    const { dlopen, FFIType } = await import('bun:ffi')
+    const libc = dlopen('libc.so.6', {
+      prctl: {
+        args: [FFIType.i32, FFIType.u64, FFIType.u64, FFIType.u64, FFIType.u64],
+        returns: FFIType.i32,
+      },
+    })
+    const ok = libc.symbols.prctl(PR_SET_DUMPABLE, 0n, 0n, 0n, 0n) === 0
+    libc.close()
+    return ok
+  } catch {
+    // No glibc (musl names it otherwise): the env stays as readable as
+    // any process's, as it was.
+    return false
+  }
+}
+
+/**
+ * Zero the value of every startup variable a task does not see by
+ * default (`ESSENTIAL_ENV` stays: every task gets it anyway). The
+ * original `envp` array follows `argv`'s NULL on the stack and is never
+ * moved, unlike `environ`, which `setenv` may reallocate. libc's
+ * `getenv` reads that block, so it answers `''` for a wiped name; vx
+ * reads `process.env`.
+ */
+async function wipeStartupEnv(): Promise<boolean> {
+  try {
+    const { dlopen, FFIType, read, toArrayBuffer, CString } = await import('bun:ffi')
+    const sys = dlopen('/usr/lib/libSystem.B.dylib', {
+      _NSGetArgv: { args: [], returns: FFIType.ptr },
+      _NSGetArgc: { args: [], returns: FFIType.ptr },
+    })
+    const argv = read.ptr(sys.symbols._NSGetArgv()!, 0)
+    const argc = read.i32(sys.symbols._NSGetArgc()!, 0)
+    sys.close()
+    const keep = new Set(ESSENTIAL_ENV)
+    for (let i = argc + 1; ; i++) {
+      const p = read.ptr(argv, i * 8)
+      if (!p) break
+      const entry = new CString(p as never).toString()
+      const eq = entry.indexOf('=')
+      if (eq < 0 || keep.has(entry.slice(0, eq))) continue
+      new Uint8Array(toArrayBuffer(p as never, 0, Buffer.byteLength(entry))).fill(0, eq + 1)
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The env for a helper vx keeps running beside its tasks (the group
+ * guard, a port bridge): PATH alone. Without an `env`, a spawn hands the
+ * child vx's startup env, and that child, dumpable after its `exec`,
+ * would show a task what `hideEnvFromTasks` hid.
+ */
+export function helperEnv(): Record<string, string> {
+  return { PATH: process.env['PATH'] ?? '' }
+}
+
+/**
+ * The env for a `git` vx runs: what git reads (`GIT_*`, the locale,
+ * `XDG_CONFIG_HOME`, the essentials: `HOME`, `PATH`) and nothing else.
+ * A git child is readable after its `exec` like any helper, and `vx
+ * watch` runs git while its tasks run.
+ */
+export function gitEnv(): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const [name, value] of Object.entries(process.env)) {
+    if (value === undefined) continue
+    if (
+      name.startsWith('GIT_') ||
+      name.startsWith('LC_') ||
+      name === 'XDG_CONFIG_HOME' ||
+      name === 'LANGUAGE' ||
+      ESSENTIAL_ENV.includes(name)
+    )
+      env[name] = value
+  }
+  return env
+}