@vzn/vx 0.0.638 → 0.0.640

package/src/{orchestrator → report}/summary.ts

@@ -5,10 +5,11 @@
 
 import type { TaskOutcome } from '../graph/index.js'
 import { tallyOutcomes } from './tally.js'
-import { isCacheHit } from './telemetry.js'
+import { isCacheHit } from '../graph/index.js'
 import { outcomeLabel, projectOutcome, ranNoCache } from './events.js'
 import { isGroupTask } from '../graph/index.js'
 import {
+  barWidth,
   ERROR,
   formatElapsed,
   gradientRule,
@@ -28,7 +29,6 @@ const ABORTED = '#f97316' // orange-500: red's neighbour, not a failure
 const NOT_RUN = '#a855f7' // purple-500: stopped before it began, apart from every other state
 const ACCENT = '#06b6d4' // cyan-500: the live region's running word
 
-const BAR_WIDTH = 50
 /**
  * Stacked state meter: one ▰ run per bucket, proportional cells via
  * largest-remainder, every non-zero bucket guaranteed at least one
@@ -41,9 +41,10 @@ function segmentBar(
 ): string {
   const total = segments.reduce((sum, seg) => sum + seg.n, 0)
   if (total === 0) return ''
-  const exact = segments.map((seg) => (seg.n / total) * BAR_WIDTH)
+  const width = barWidth(colors)
+  const exact = segments.map((seg) => (seg.n / total) * width)
   const cells = exact.map(Math.floor)
-  let leftover = BAR_WIDTH - cells.reduce((sum, c) => sum + c, 0)
+  let leftover = width - cells.reduce((sum, c) => sum + c, 0)
   const order = exact
     .map((e, i) => ({ i, frac: e - Math.floor(e) }))
     .sort((x, y) => y.frac - x.frac)
@@ -61,9 +62,12 @@ function segmentBar(
   }
   return segments
     .map((seg, i) =>
-      paint(seg.color, (seg.glyph ?? '\u25b0').repeat(cells[i]!), colors, {
-        ...(seg.dim === true ? { dim: true } : {}),
-      }),
+      // An empty segment paints nothing: no escape pair around no cell.
+      cells[i] === 0
+        ? ''
+        : paint(seg.color, (seg.glyph ?? '\u25b0').repeat(cells[i]!), colors, {
+            ...(seg.dim === true ? { dim: true } : {}),
+          }),
     )
     .join('')
 }
@@ -106,6 +110,67 @@ export interface SummaryStats {
   savedMs?: number
   /** A run of groups only: their names, so `0 tasks` says why. */
   emptyGroups?: readonly string[]
+  /** Each finished task's cache bucket by its key, so its remote traffic can move it. */
+  buckets?: ReadonlyMap<string, CacheBucket>
+}
+
+/** The cache bar segment a finished task fills before its remote traffic is weighed. */
+export type CacheBucket =
+  | 'miss'
+  | 'noCache'
+  | 'upToDate'
+  | 'restoredLocal'
+  | 'restoredRemote'
+  | 'saved'
+
+/** A finished task's own cache bucket; none for a group, a skip or an abort. */
+export function cacheBucketOf(o: TaskOutcome): CacheBucket | undefined {
+  if (isGroupTask(o.node)) return undefined
+  switch (o.status) {
+    case 'success':
+      return ranNoCache(o) ? 'noCache' : o.saved === true ? 'saved' : 'miss'
+    case 'failed':
+      return ranNoCache(o) ? 'noCache' : 'miss'
+    case 'cache-hit':
+      return o.restored === false ? 'upToDate' : 'restoredLocal'
+    case 'cache-hit-remote':
+      return o.restored === false ? 'upToDate' : 'restoredRemote'
+    default:
+      return undefined
+  }
+}
+
+type Buckets = Record<CacheBucket | 'uploaded' | 'uploading' | 'remoteFailed', number>
+
+/**
+ * The cache bar's segments, each task in one (M, 2026-10-15). With layers
+ * named, a saved task leaves the misses, and a task with remote traffic
+ * leaves its own bucket for its strongest remote state: a failed read or
+ * write, then an upload still running, then one that landed. Without, the
+ * plain legend's buckets.
+ */
+function cacheBuckets(stats: SummaryStats, layers: RunContext['cache']): Buckets {
+  const saved = layers === undefined ? 0 : (stats.saved ?? 0)
+  const b: Buckets = {
+    miss: stats.miss - saved,
+    noCache: stats.noCache ?? 0,
+    upToDate: stats.upToDate,
+    restoredLocal: stats.restoredLocal,
+    restoredRemote: stats.restoredRemote,
+    saved,
+    uploaded: 0,
+    uploading: 0,
+    remoteFailed: 0,
+  }
+  if (layers?.remote !== true || stats.buckets === undefined) return b
+  for (const [hash, k] of layers.traffic.keys) {
+    const from = stats.buckets.get(hash)
+    // Still running: it counts once it ends.
+    if (from === undefined) continue
+    b[from]--
+    b[k.failures.length > 0 ? 'remoteFailed' : k.uploading > 0 ? 'uploading' : 'uploaded']++
+  }
+  return b
 }
 
 /**
@@ -116,7 +181,7 @@ export interface SummaryStats {
  */
 export interface RunContext {
   version: string
-  /** Projects covered by the graph — the "affected" half of the bar. */
+  /** Projects with a real task in the graph — the "affected" half of the bar. */
   packageCount: number
   /** Worker-pool size for this run; shown on the `info` row. */
   concurrency?: number
@@ -131,8 +196,12 @@ export interface RunContext {
     localWrite: boolean
     /** A remote layer exists and the policy reads or writes it. */
     remote: boolean
-    /** The run's uploads, filled as each lands (a live ref). */
-    uploads: { count: number; failed: number }
+    /** The run's remote traffic per key, filled as it happens (a live ref). */
+    traffic: {
+      /** Uploads queued or running. */
+      readonly inFlight: number
+      readonly keys: ReadonlyMap<string, { uploading: number; failures: readonly string[] }>
+    }
     /** Tasks whose outputs are still in the remote store. */
     notDownloaded: () => number
   }
@@ -196,13 +265,14 @@ export function formatSummarySection(
   if (context !== undefined) {
     const wsTotal = context.workspaceProjectCount
     if (wsTotal !== undefined && wsTotal > 0) {
+      const width = barWidth(colors)
       const cells = Math.min(
-        BAR_WIDTH,
-        Math.max(1, Math.round((context.packageCount / wsTotal) * BAR_WIDTH)),
+        width,
+        Math.max(1, Math.round((context.packageCount / wsTotal) * width)),
       )
       const bar =
         paint(WARN, '▰'.repeat(cells), colors) +
-        paint('', '▱'.repeat(BAR_WIDTH - cells), colors, { dim: true })
+        paint('', '▱'.repeat(width - cells), colors, { dim: true })
       lines.push(
         row('projects', bar),
         legend([paint(WARN, `${context.packageCount} affected`, colors), dim(`${wsTotal} total`)]),
@@ -230,37 +300,48 @@ export function formatSummarySection(
   // Cache meter + numbers: per layer when the run context names its
   // layers, else miss · no-cache · up-to-date · local · remote.
   if (miss + noCache + hits + left + stats.skipped > 0) {
+    const layers = context?.cache
+    const b = cacheBuckets(stats, layers)
     const cacheBar = segmentBar(
       [
-        { n: miss, color: ERROR },
-        { n: noCache, color: '', dim: true },
-        { n: stats.upToDate, color: SUCCESS },
-        { n: stats.restoredLocal, color: LOCAL },
-        { n: stats.restoredRemote, color: REMOTE },
+        { n: b.miss, color: ERROR },
+        { n: b.noCache, color: '', dim: true },
+        { n: b.upToDate, color: SUCCESS },
+        { n: b.restoredLocal, color: LOCAL },
+        { n: b.saved, color: LOCAL },
+        { n: b.restoredRemote, color: REMOTE },
+        { n: b.uploaded, color: REMOTE },
+        { n: b.uploading, color: ACCENT },
+        { n: b.remoteFailed, color: ERROR },
         { n: stats.skipped, color: WARN },
         remainder,
       ],
       colors,
     )
     const cacheParts: string[] = []
-    const layers = context?.cache
     if (layers !== undefined) {
-      // Per layer (M, 2026-10-15): `●` fresh (outputs already on disk, from
-      // either layer) and `○` no cache, both local; `↓` restored from a
-      // layer, `↑` saved to it.
-      const n = (count: number, glyph: string): string[] => (count > 0 ? [`${count}${glyph}`] : [])
+      // Per layer (M, 2026-10-15): `✓` fresh (outputs already on disk, from
+      // either layer) and `∅` no cache, both local; `↓` restored from a
+      // layer, `↑` saved to it; `✗` a remote read or write failed, `⇡` still
+      // uploading. Each count is its bar segment's, glyph and number in its colour.
+      const n = (count: number, glyph: string, color: string, dim = false): string[] =>
+        count > 0 ? [paint(color, `${count}${glyph}`, colors, dim ? { dim: true } : {})] : []
       const local = [
-        ...(layers.local ? n(stats.upToDate, '\u25cf') : []),
-        ...n(noCache, '\u25cb'),
-        ...(layers.local ? n(stats.restoredLocal, '\u2193') : []),
-        ...(layers.localWrite ? n(stats.saved ?? 0, '\u2191') : []),
+        ...(layers.local ? n(b.upToDate, '\u2713', SUCCESS) : []),
+        ...n(b.noCache, '\u2205', '', true),
+        ...(layers.local ? n(b.restoredLocal, '\u2193', LOCAL) : []),
+        ...(layers.localWrite ? n(b.saved, '\u2191', LOCAL) : []),
+      ]
+      // The layer words are dim; only the counts carry colour (M, 2026-10-15).
+      if (local.length > 0) cacheParts.push(`${dim('local')} ${local.join(' ')}`)
+      const remote = [
+        ...n(b.restoredRemote, '\u2193', REMOTE),
+        ...n(b.uploaded, '\u2191', REMOTE),
+        ...n(b.remoteFailed, '\u2717', ERROR),
+        ...n(b.uploading, '\u21e1', ACCENT),
       ]
-      if (local.length > 0) cacheParts.push(paint(LOCAL, `local ${local.join(' ')}`, colors))
-      const remote = [...n(stats.restoredRemote, '\u2193'), ...n(layers.uploads.count, '\u2191')]
       if (layers.remote && remote.length > 0)
-        cacheParts.push(paint(REMOTE, `remote ${remote.join(' ')}`, colors))
-      if (layers.uploads.failed > 0)
-        cacheParts.push(paint(ERROR, `${layers.uploads.failed} \u2191 failed`, colors))
+        cacheParts.push(`${dim('remote')} ${remote.join(' ')}`)
       if ((stats.notSaved ?? 0) > 0)
         cacheParts.push(paint(WARN, `${stats.notSaved} not saved`, colors))
       const notDownloaded = layers.notDownloaded()
@@ -393,9 +474,8 @@ export function formatRunSummary(
   colors: ColorSupport = NO_COLOR,
   context?: RunContext,
 ): string[] {
-  // Counted here, not in the Tally: that object is the `--summarize` payload
-  // (ten documented fields) and a task with no `cache` block is a terminal
-  // distinction — it never consulted the cache, so it is not a miss.
+  // Counted here, not in the Tally: a task with no `cache` block never
+  // consulted the cache, so it is not a miss.
   const noCache = outcomes.filter(
     (o) =>
       !isGroupTask(o.node) && (o.status === 'success' || o.status === 'failed') && ranNoCache(o),
@@ -448,6 +528,7 @@ export function formatRunSummary(
           }
         : {}),
       ...(emptyGroups.length > 0 ? { emptyGroups } : {}),
+      buckets: bucketsOf(outcomes),
     },
     totalMs,
     colors,
@@ -455,6 +536,16 @@ export function formatRunSummary(
   )
 }
 
+/** Each finished task's cache bucket by its key. */
+function bucketsOf(outcomes: readonly TaskOutcome[]): Map<string, CacheBucket> {
+  const out = new Map<string, CacheBucket>()
+  for (const o of outcomes) {
+    const bucket = o.hash === undefined ? undefined : cacheBucketOf(o)
+    if (bucket !== undefined) out.set(o.hash!, bucket)
+  }
+  return out
+}
+
 /**
  * An `aborted` outcome the stop reached before dispatch. The scheduler gives
  * it an invented exit 1; only a started task carries a wall-clock start, so

package/src/report/tally.ts

@@ -0,0 +1,83 @@
+// Outcome tally for the end-of-run footer (`summary.ts`): the bucket rules,
+// group tasks excluded.
+
+import { isGroupTask, type TaskOutcome } from '../graph/index.js'
+
+export interface Tally {
+  successful: number
+  failed: number
+  skipped: number
+  cachedLocal: number
+  /** Hits that materialized files from the local artifact. */
+  restoredLocal: number
+  /** Hits that materialized files pulled from the remote layer. */
+  restoredRemote: number
+  /** Cache hits whose tree already matched — nothing was written. */
+  upToDate: number
+  cachedRemote: number
+  /**
+   * Killed by a shutdown signal. No work, so it joins no outcome bucket and
+   * not `total` — but it is counted, because it makes the run red: a red run
+   * whose every counted task succeeded is undiagnosable without this.
+   */
+  aborted: number
+  /** Tasks counted toward `total`. Group tasks are excluded by default. */
+  total: number
+}
+
+function emptyTally(): Tally {
+  return {
+    successful: 0,
+    failed: 0,
+    skipped: 0,
+    cachedLocal: 0,
+    restoredLocal: 0,
+    restoredRemote: 0,
+    upToDate: 0,
+    cachedRemote: 0,
+    aborted: 0,
+    total: 0,
+  }
+}
+
+/**
+ * Walk live outcomes and return a `Tally` — the single owner of the bucket
+ * rules.
+ *
+ * Group tasks (no `exec`) aren't real work; including them inflates the
+ * per-run "N total" count in ways that mislead ("3 of 4 cached" when one was
+ * a group that ran nothing).
+ *
+ * Status bucket rules:
+ *   `success`            → +successful
+ *   `cache-hit`          → +successful, +cachedLocal
+ *   `cache-hit-remote`   → +successful, +cachedRemote
+ *   `failed`             → +failed
+ *   `skipped`            → +skipped
+ *   `aborted`            → +aborted only (no bucket, no total)
+ */
+export function tallyOutcomes(outcomes: readonly TaskOutcome[]): Tally {
+  const t = emptyTally()
+  for (const o of outcomes) {
+    if (isGroupTask(o.node)) continue
+    if (o.status === 'aborted') {
+      t.aborted++
+      continue
+    }
+    t.total++
+    if (o.status === 'success') t.successful++
+    else if (o.status === 'cache-hit') {
+      t.successful++
+      t.cachedLocal++
+      if (o.restored === true) t.restoredLocal++
+      else t.upToDate++
+    } else if (o.status === 'cache-hit-remote') {
+      t.successful++
+      t.cachedRemote++
+      if (o.restored === true) t.restoredRemote++
+      else t.upToDate++
+    } else if (o.status === 'failed') t.failed++
+    else if (o.status === 'skipped') t.skipped++
+  }
+  return t
+}

package/src/settings.ts

@@ -102,39 +102,12 @@ export const SETTINGS: readonly Setting[] = [
     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' },
@@ -197,6 +170,13 @@ export const SETTINGS: readonly Setting[] = [
     task: 'cache.outputs.clean',
     env: false,
   },
+  {
+    path: 'cache.upload.failures',
+    kind: { type: 'enum', values: ['ci', 'local', 'always'] },
+    default: 'ci',
+    doc: "Where a failed task's log and outputs are kept in the remote: CI runs, local runs, or both.",
+    env: false,
+  },
   {
     path: 'lock.reviewFiles',
     kind: { type: 'bool' },
@@ -249,7 +229,7 @@ export function setting(path: string): Setting {
   return BY_PATH.get(path)!
 }
 
-/** `run.killGrace` → `VX_RUN_KILL_GRACE`. */
+/** `run.affectedBase` → `VX_RUN_AFFECTED_BASE`. */
 export function envName(path: string): string {
   return `VX_${path
     .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
@@ -414,15 +394,8 @@ export function resolveSetting(
   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
+/** `run.rules`, from its variable, else the workspace; unset stays on. */
+export function runRules(workspace: unknown): { exclusiveOutputs?: boolean } {
+  const { value } = resolveSetting('run.rules.exclusiveOutputs', workspace)
+  return value === undefined ? {} : { exclusiveOutputs: value as boolean }
 }

package/src/util/colors.ts

@@ -20,6 +20,8 @@ export const ERROR = '#ef4444'
 
 export interface ColorSupport {
   enabled: boolean
+  /** The terminal's width, read live; none off a terminal. Bars and rules fit it. */
+  readonly columns?: number | undefined
 }
 
 export interface PaintOptions {
@@ -32,16 +34,32 @@ export interface PaintOptions {
  *   NO_COLOR non-empty          → off (overrides FORCE_COLOR)
  *   FORCE_COLOR=0 or =false     → off, even on a TTY
  *   FORCE_COLOR any other value → on (the empty string too)
- *   else: on iff stdout is a TTY.
+ *   else: on iff stdout is a TTY that is not `TERM=dumb`.
  * `0` and `false` are the convention's "off" (supports-color, chalk,
  * Node); reading every non-empty value as on painted a piped CI log that
  * set `FORCE_COLOR=0` (nx#35292's bug).
  */
 export function detectColors(stream: NodeJS.WriteStream = process.stdout): ColorSupport {
-  if (process.env['NO_COLOR']) return { enabled: false }
   const force = process.env['FORCE_COLOR']
-  if (force !== undefined) return { enabled: force !== '0' && force !== 'false' }
-  return { enabled: stream.isTTY === true }
+  const enabled = process.env['NO_COLOR']
+    ? false
+    : force !== undefined
+      ? force !== '0' && force !== 'false'
+      : stream.isTTY === true && !dumbTerminal()
+  return {
+    enabled,
+    get columns() {
+      return stream.isTTY === true ? stream.columns : undefined
+    },
+  }
+}
+
+/**
+ * `TERM=dumb` (Emacs `M-x shell`, some CI log viewers) can neither paint
+ * nor move the cursor: vx prints to it as off a terminal.
+ */
+export function dumbTerminal(): boolean {
+  return process.env['TERM'] === 'dumb'
 }
 
 // Bun.color() is pure for a given (hex, mode) pair but does FFI work
@@ -71,3 +89,25 @@ export function paint(
   if (prefix.length === 0) return text
   return `${prefix}${text}${RESET}`
 }
+
+/**
+ * Identity hues for the two halves of a `project#task` id, never a status
+ * colour: one name, one hue, in every run, list and row (M, 2026-10-15:
+ * every `#build` matches every other `#build`).
+ */
+const IDENTITY_PALETTE = [
+  '#a78bfa', // violet-400
+  '#60a5fa', // blue-400
+  '#e879f9', // fuchsia-400
+  '#818cf8', // indigo-400
+  '#c084fc', // purple-400
+  '#93c5fd', // blue-300
+  '#f472b6', // pink-400
+] as const
+
+/** A project's or a target's hue: a fold of the name into the palette. */
+export function identityColor(name: string): string {
+  let h = 0
+  for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) >>> 0
+  return IDENTITY_PALETTE[h % IDENTITY_PALETTE.length]!
+}

package/src/util/git-ignored.ts

@@ -0,0 +1,143 @@
+// Whether git ignores everything an output glob can write (M, 2026-10-15):
+// a key reads only what git lists, so such an output never reaches a
+// reader's key. Asked of git, never read from a `.gitignore`: git alone
+// knows every rule source (nested files, `info/exclude`, `core.excludesFile`)
+// and that a directory holding a tracked file is not ignored.
+
+import { gitEnv } from './hide-env.js'
+import { isLiteralPattern, normalizeGlob } from './paths.js'
+import { executablePath } from './which.js'
+
+/** A directory name no ignore rule names, standing for one a task may create. */
+const FRESH = '__vx_probe__'
+
+/**
+ * The paths git is asked about for a root-relative output glob: when git
+ * ignores each, it ignores every untracked path the glob can match. `deep`:
+ * the glob reaches below them (a `dist` at any depth is asked as `dist/` and
+ * a fresh `__vx_probe__/dist/`), so a listed file it matches must be looked
+ * for too (a tracked one, or one a `!` rule takes back). Null when no few paths
+ * stand for the glob (`*.js`): undecided, the output overlaps as before.
+ * `dir`: the glob's literal directory, where a listed file it matches lies.
+ */
+export function ignoreProbes(glob: string): { paths: string[]; deep: boolean; dir: string } | null {
+  const segs = normalizeGlob(glob).split('/')
+  let i = 0
+  while (i < segs.length && isLiteralPattern(segs[i]!)) i++
+  const lit = segs.slice(0, i).join('/')
+  if (i === segs.length) return { paths: [lit], deep: false, dir: lit }
+  const at = lit === '' ? '' : `${lit}/`
+  const name = segs[i + 1]
+  if (segs[i] === '**' && name !== undefined && isLiteralPattern(name)) {
+    const leaf = i + 2 < segs.length ? `${name}/` : name
+    return { paths: [at + leaf, `${at}${FRESH}/${leaf}`], deep: true, dir: lit }
+  }
+  return lit === '' ? null : { paths: [`${lit}/`], deep: false, dir: lit }
+}
+
+const CHECK_IGNORE = ['check-ignore', '--stdin', '-z']
+
+function ignoredOf(exitCode: number, stdout: Uint8Array): Set<string> | null {
+  // 0: some ignored; 1: none; anything else (no work tree): undecided.
+  if (exitCode === 1) return new Set()
+  if (exitCode !== 0) return null
+  return new Set(
+    new TextDecoder()
+      .decode(stdout)
+      .split('\0')
+      .filter((p) => p !== ''),
+  )
+}
+
+/** The `paths` (relative to `cwd`) git ignores; null when git cannot say. */
+export async function checkIgnore(
+  cwd: string,
+  paths: readonly string[],
+): Promise<Set<string> | null> {
+  if (paths.length === 0) return new Set()
+  try {
+    const proc = Bun.spawn({
+      cmd: [executablePath('git'), ...CHECK_IGNORE],
+      env: gitEnv(),
+      cwd,
+      stdin: Buffer.from(paths.map((p) => `${p}\0`).join('')),
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    const stdout = await new Response(proc.stdout).bytes()
+    return ignoredOf(await proc.exited, stdout)
+  } catch {
+    return null
+  }
+}
+
+/** {@link checkIgnore} for `vx lock`, which builds its graph synchronously. */
+export function checkIgnoreSync(cwd: string, paths: readonly string[]): Set<string> | null {
+  if (paths.length === 0) return new Set()
+  try {
+    const r = Bun.spawnSync({
+      cmd: [executablePath('git'), ...CHECK_IGNORE],
+      env: gitEnv(),
+      cwd,
+      stdin: Buffer.from(paths.map((p) => `${p}\0`).join('')),
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    return ignoredOf(r.exitCode, r.stdout)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * What git lists under `dirs` (relative to `cwd`): tracked files and the
+ * untracked ones it does not ignore, the set a key filters. Null when git
+ * cannot say. A run has it from its enumeration; this is `vx lock`'s.
+ */
+export function listedSync(cwd: string, dirs: readonly string[]): string[] | null {
+  try {
+    const r = Bun.spawnSync({
+      cmd: [
+        executablePath('git'),
+        'ls-files',
+        '-z',
+        '--cached',
+        '--others',
+        '--exclude-standard',
+        '--',
+        ...dirs.map((d) => (d === '' ? '.' : `:(literal)${d}`)),
+      ],
+      env: gitEnv(),
+      cwd,
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    if (r.exitCode !== 0) return null
+    return new TextDecoder()
+      .decode(r.stdout)
+      .split('\0')
+      .filter((p) => p !== '')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Of `globs` (root-relative), those git ignores whole: each probe ignored
+ * and, for a deep glob, no listed file it matches (`listedMatch`).
+ */
+export function wholeIgnored(
+  globs: Iterable<string>,
+  ignored: ReadonlySet<string> | null,
+  listedMatch: (glob: string) => boolean,
+): Set<string> {
+  const out = new Set<string>()
+  if (ignored === null) return out
+  for (const g of globs) {
+    const ask = ignoreProbes(g)
+    if (ask === null || !ask.paths.every((p) => ignored.has(p))) continue
+    if (ask.deep && listedMatch(g)) continue
+    out.add(g)
+  }
+  return out
+}

package/src/util/index.ts

@@ -24,8 +24,17 @@ export {
   wantsJson,
 } from './errors.js'
 export { configErrorFrame, configRefusal } from './config-frame.js'
-export { detectColors, ERROR, paint, SUCCESS, WARN, type ColorSupport } from './colors.js'
-export { gradientRule } from './report.js'
+export {
+  detectColors,
+  dumbTerminal,
+  ERROR,
+  identityColor,
+  paint,
+  SUCCESS,
+  WARN,
+  type ColorSupport,
+} from './colors.js'
+export { barWidth, gradientRule } from './report.js'
 import * as ui from './ui.js'
 export { refusalNotice, sayLine, sayNotice } from './refusal-notice.js'
 export { ui }
@@ -67,10 +76,9 @@ export {
   claimExitForSignal,
   exitClaimedBySignal,
   killGraceMs,
-  setSettleBounds,
-  type SettleBound,
   settleWithin,
   teardownTimeoutMs,
+  testTimerMs,
 } from './settle.js'
 export { formatBytes, parseDuration, parseSize, treeBytes } from './size.js'
 export {
@@ -91,6 +99,13 @@ export { procfsIsOwn } from './procfs.js'
 export { hangupIgnored } from './hangup.js'
 export { ESSENTIAL_ENV } from './essential-env.js'
 export { gitEnv, helperEnv, hideEnvFromTasks } from './hide-env.js'
+export {
+  checkIgnore,
+  checkIgnoreSync,
+  ignoreProbes,
+  listedSync,
+  wholeIgnored,
+} from './git-ignored.js'
 export { realPath, realpathOf } from './real-path.js'
 export {
   maskedCommand,