@vzn/vx 0.0.21 → 0.0.22

package/src/cli/last.ts

@@ -7,7 +7,13 @@
 import { Cache, noteSchemaReset } from '../cache/index.js'
 import { formatBytes } from './format.js'
 import { seeHelp } from './help.js'
-import { getInvocation, getRun, listInvocations } from '../orchestrator/index.js'
+import {
+  exitSignal,
+  getInvocation,
+  getRun,
+  listInvocations,
+  type RunSummaryRow,
+} from '../orchestrator/index.js'
 import { UserError } from '../util/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import { cliCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
@@ -26,7 +32,14 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
   for (let i = 0; i < args.length; i++) {
     const a = args[i]!
     if (a === '--list' || a.startsWith('--list=')) {
-      const lv = a === '--list' ? '10' : a.slice(7)
+      // `--list 5` is the count, like every other value flag's space form:
+      // it read as a run id, which `--list` then ignored, and ten runs came
+      // back (item 899). A run id is never a bare integer, so the next
+      // argument is taken only when it is one.
+      const next = args[i + 1]
+      const spaced = a === '--list' && next !== undefined && /^\d+$/.test(next)
+      const lv = a === '--list' ? (spaced ? next : '10') : a.slice(7)
+      if (spaced) i++
       const n = Number(lv)
       if (!Number.isInteger(n) || n < 1 || n > 500) {
         return { ...out, error: `invalid --list: ${lv} (expected 1..500)` }
@@ -53,6 +66,13 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
     if (out.runId !== undefined) return { ...out, error: `unexpected argument: ${a}` }
     out.runId = a
   }
+  // One run's replay or a list of runs, not both: the id was dropped.
+  if (out.runId !== undefined && out.list !== undefined) {
+    return {
+      ...out,
+      error: `a run id and --list do not combine: replay ${out.runId}, or list runs`,
+    }
+  }
   return out
 }
 
@@ -83,12 +103,84 @@ function fmtUsage(t: {
   return parts.length > 0 ? `  ${parts.join(' · ')}` : ''
 }
 
+/**
+ * Why a row failed or was skipped, as the run's own footer said it (the
+ * v27 columns): a timeout or a never-ready server instead of the signal
+ * their exit stands for, the sandbox's violation count, a skip's blocker.
+ * Older rows carry none and read as before.
+ */
+function reasonParts(t: RunSummaryRow): string {
+  const parts: string[] = []
+  if (t.status === 'failed') {
+    if (t.notReady !== null) {
+      parts.push(
+        `never ready: ${t.notReady === 'timeout' ? 'timed out' : t.notReady === 'exited' ? 'exited' : 'spawn failed'}`,
+      )
+    } else if (t.timedOut === true) {
+      parts.push('timed out')
+    } else {
+      const signal = exitSignal(t.exitCode)
+      if (signal !== undefined) parts.push(`128 + ${signal}`)
+    }
+    if (t.sandboxViolations !== null && t.sandboxViolations > 0) {
+      parts.push(`${t.sandboxViolations} sandbox violation${t.sandboxViolations === 1 ? '' : 's'}`)
+    }
+  } else if (t.status === 'skipped' && t.blockedBy !== null) {
+    parts.push(`after ${t.blockedBy} failed`)
+  }
+  return parts.map((p) => `  ${p}`).join('')
+}
+
+/** Hit rows shown before the rest fold — the slowest restores. */
+const HITS_SHOWN = 16
+
+/**
+ * The per-task rows: failures first, then what executed or was skipped,
+ * then cache hits. Hits are the noise of a warm run — 996 of a thousand
+ * rows on a red run put the failure a screen's height above the prompt
+ * (item 280) — so past `HITS_SHOWN` they fold into one line with their
+ * count; the ones shown are the slowest restores, the one thing a hit's
+ * row tells. `--format json` lists every row.
+ */
+export function formatTaskRows(tasks: readonly RunSummaryRow[]): string[] {
+  if (tasks.length === 0) return []
+  const failed = tasks.filter((t) => t.status === 'failed')
+  const hits = tasks.filter((t) => t.status !== 'failed' && t.cacheHit === true)
+  const rest = tasks.filter((t) => t.status !== 'failed' && t.cacheHit !== true)
+  const folded = hits.length > HITS_SHOWN
+  const shownHits = folded
+    ? [...hits].sort((a, b) => b.durationMs - a.durationMs).slice(0, HITS_SHOWN)
+    : hits
+  const ordered = [...failed, ...rest, ...shownHits]
+  const idW = Math.max(...ordered.map((t) => `${t.project}#${t.task}`.length), 4)
+  const lines = ['']
+  for (const t of ordered) {
+    const id = `${t.project}#${t.task}`
+    // The terminal summary's own word for a task that runs every time
+    // by design; a reader must not take its row for a miss.
+    // A failure's row reads as the frame did — `failed (exit 137)` —
+    // and above 128 names the signal the number stands for (260).
+    const status = t.status === 'failed' ? `failed (exit ${t.exitCode})` : t.status
+    lines.push(
+      `  ${status.padEnd(17)} ${id.padEnd(idW)}  ${fmtMs(t.durationMs).padStart(8)}` +
+        `${t.hash !== '' ? `  ${t.hash}` : ''}${t.cached === false ? '  no-cache' : ''}${fmtUsage(t)}` +
+        reasonParts(t),
+    )
+  }
+  if (folded) {
+    lines.push(
+      `  … +${hits.length - HITS_SHOWN} more cache hits (the ${HITS_SHOWN} slowest restores shown) — vx last --format json lists every row`,
+    )
+  }
+  return lines
+}
+
 export async function lastCmd(args: readonly string[]): Promise<number> {
   const parsed = parseLastArgs(args)
   if (parsed.error !== undefined) throw new UserError(`vx last: ${parsed.error}`)
 
   const root = await findWorkspaceRoot(process.cwd())
-  const cache = new Cache(await cliCacheDir(root, parsed.cacheDir))
+  const cache = Cache.inspect(await cliCacheDir(root, parsed.cacheDir))
   noteSchemaReset(cache, warnToStderr)
   try {
     const db = cache.dbHandle()
@@ -146,24 +238,7 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
         ` (${inv.hitLocalCount} local, ${inv.hitRemoteCount} remote)` +
         `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''}`,
     )
-    const tasks = detail?.tasks ?? []
-    if (tasks.length > 0) {
-      lines.push('')
-      const failedFirst = [
-        ...tasks.filter((t) => t.status === 'failed'),
-        ...tasks.filter((t) => t.status !== 'failed'),
-      ]
-      const idW = Math.max(...tasks.map((t) => `${t.project}#${t.task}`.length), 4)
-      for (const t of failedFirst) {
-        const id = `${t.project}#${t.task}`
-        // The terminal summary's own word for a task that runs every time
-        // by design; a reader must not take its row for a miss.
-        lines.push(
-          `  ${t.status.padEnd(17)} ${id.padEnd(idW)}  ${fmtMs(t.durationMs).padStart(8)}` +
-            `${t.hash !== '' ? `  ${t.hash}` : ''}${t.cached === false ? '  no-cache' : ''}${fmtUsage(t)}`,
-        )
-      }
-    }
+    lines.push(...formatTaskRows(detail?.tasks ?? []))
     process.stdout.write(`${lines.join('\n')}\n`)
     return 0
   } finally {

package/src/cli/lock.ts

@@ -7,6 +7,7 @@ import { seeHelp } from './help.js'
 import { relPosix, xxh3hex } from '../util/index.js'
 import {
   findWorkspaceRoot,
+  type LoadReads,
   listProjects,
   loadProjectConfig,
   loadWorkspace,
@@ -41,32 +42,42 @@ export async function lockCmd(args: readonly string[]): Promise<number> {
     process.stderr.write(`vx lock: ${parsed.error}\n`)
     return 1
   }
-  const root = await findWorkspaceRoot(process.cwd())
-  const workspace = await loadWorkspace(root)
-  const metas = (await listProjects(workspace)).filter(
-    (m): m is ConfiguredMeta => m.configPath !== null,
-  )
-  if (parsed.check) return await checkLock(root, metas)
-  return await writeLock(root, metas)
+  const reads: LoadReads = new Map()
+  const root = await findWorkspaceRoot(process.cwd(), reads)
+  const workspace = await loadWorkspace(root, reads)
+  const all = await listProjects(workspace)
+  const metas = all.filter((m): m is ConfiguredMeta => m.configPath !== null)
+  // A project with no vx.config has nothing to freeze: its tasks (a plugin's,
+  // or none) load live under --frozen too, so both verbs say how many the
+  // count above leaves out — `locked 0 project configs` on a turbo() repo
+  // read like an audit of something (2026-09-16).
+  const bare = all.length - metas.length
+  if (parsed.check) return await checkLock(root, metas, bare)
+  return await writeLock(root, metas, bare)
 }
 
 /** Evaluate one config in the current env, returning its lock entry. */
 async function evaluateEntry(root: string, meta: ConfiguredMeta): Promise<LockfileEntry> {
   const bytes = await Bun.file(meta.configPath).bytes()
-  // `fresh: true` — locking must observe the current environment, not
-  // a module-cache replay from earlier in this process.
+  // `fresh: true` — the lock freezes this environment's evaluation, never
+  // a stored one, whatever options a later edit passes beside it.
   const config = await loadProjectConfig(meta.configPath, { fresh: true })
   return {
     configPath: relPosix(root, meta.configPath),
     configHash: xxh3hex(bytes),
-    // JSON round-trip drops `undefined` fields so the stored object is
-    // byte-identical to what a later read of the lock will produce —
-    // the exact form `--check` compares against.
-    config: JSON.parse(JSON.stringify(config)) as ProjectConfig,
+    // Stored through `writeLockfile`'s JSON.stringify, which drops a field
+    // left `undefined` — the form `--check` compares a fresh evaluation in.
+    config,
   }
 }
 
-async function writeLock(root: string, metas: ConfiguredMeta[]): Promise<number> {
+function bareNote(bare: number): string {
+  return bare === 0
+    ? ''
+    : ` (${bare} project${bare === 1 ? ' has' : 's have'} no vx.config; their tasks are never frozen)`
+}
+
+async function writeLock(root: string, metas: ConfiguredMeta[], bare: number): Promise<number> {
   const entries = await Promise.all(metas.map((m) => evaluateEntry(root, m)))
   const projects: Record<string, LockfileEntry> = {}
   // `listProjects` sorts by name — stable lockfile diffs for free.
@@ -74,7 +85,9 @@ async function writeLock(root: string, metas: ConfiguredMeta[]): Promise<number>
   const lock: Lockfile = { version: LOCKFILE_VERSION, projects }
   await writeLockfile(root, lock)
   const n = metas.length
-  process.stdout.write(`vx: locked ${n} project config${n === 1 ? '' : 's'} → ${LOCKFILE_NAME}\n`)
+  process.stdout.write(
+    `vx: locked ${n} project config${n === 1 ? '' : 's'} → ${LOCKFILE_NAME}${bareNote(bare)}\n`,
+  )
   return 0
 }
 
@@ -86,7 +99,7 @@ async function writeLock(root: string, metas: ConfiguredMeta[]): Promise<number>
  *      catches eval-time env-var drift that file hashes cannot see —
  *      file bytes unchanged, resolved value changed.
  */
-async function checkLock(root: string, metas: ConfiguredMeta[]): Promise<number> {
+async function checkLock(root: string, metas: ConfiguredMeta[], bare: number): Promise<number> {
   const lock = await readLockfile(root)
   if (!lock) {
     process.stderr.write(
@@ -105,6 +118,8 @@ async function checkLock(root: string, metas: ConfiguredMeta[]): Promise<number>
       if (hash !== entry.configHash) {
         return `config file changed since lock (${m.name}: ${rel}) — run 'vx lock'`
       }
+      // The lock's form: a first load is the module's live export, where a
+      // field left `undefined` is a key the stored JSON never has.
       const fresh = JSON.parse(
         JSON.stringify(await loadProjectConfig(m.configPath, { fresh: true })),
       ) as ProjectConfig
@@ -131,6 +146,8 @@ async function checkLock(root: string, metas: ConfiguredMeta[]): Promise<number>
     return 1
   }
   const n = metas.length
-  process.stdout.write(`vx: lock is up to date (${n} project${n === 1 ? '' : 's'})\n`)
+  const audited = `${n} project${n === 1 ? '' : 's'}`
+  const skipped = bare === 0 ? '' : `; ${bare} without a vx.config not audited`
+  process.stdout.write(`vx: lock is up to date (${audited}${skipped})\n`)
   return 0
 }

package/src/cli/plan-format.ts

@@ -9,12 +9,12 @@ import { formatDuration } from '../orchestrator/index.js'
  * task with recorded history also shows its typical duration (~p50).
  *
  *   would run:
- *     ✓  @vzn/vx#lint       cache hit (local)        abc12345
+ *     ◉  @vzn/vx#lint       cache hit (local)        abc12345
  *     ↓  @vzn/vx#test       cache hit (remote)       def67890
- *     ▶  @vzn/vx#build      cache miss — would exec  fedcba98  ~1.2s
+ *     ▶  @vzn/vx#build      cache miss — would exec  fedcba98  ~1.20s
  *
- *   3 task(s) planned: 2 cache hits (1 local, 1 remote), 1 would run.
- *   predicted: ~1.2s wall · ~1.2s total execution
+ *   3 task(s) planned, 2 cache hits (1 local, 1 remote), 1 would run.
+ *   predicted: ~1.20s wall · ~1.20s total execution
  */
 export function formatPlanText(plan: RunPlan): string {
   const real = plan.tasks.filter((t) => t.cacheStatus !== 'group')

package/src/cli/plugin-commands.ts

@@ -17,6 +17,17 @@ export interface ResolvedPluginCommand {
   ctx: CommandContext
 }
 
+/**
+ * No plugin here declares the verb, and these are the verbs they DO declare
+ * — the same load that failed to find the verb already knows them, so the
+ * "did you mean" and the "where verbs come from" line cost nothing extra.
+ * An empty list is a workspace whose plugins declare no verb at all; `null`
+ * from the lookup is no workspace.
+ */
+interface NoPluginCommand {
+  declaredVerbs: readonly string[]
+}
+
 /**
  * Why a verb could not be looked up: the workspace file failed to load.
  * Surfaced next to "unknown command" rather than as the whole answer — a
@@ -50,17 +61,21 @@ async function workspacePlugins(
 }
 
 /**
- * The plugin verb named `verb` for the workspace around `cwd`; null when
- * there is none; the load error when the workspace file could not say.
+ * The plugin verb named `verb` for the workspace around `cwd`; the verbs
+ * this workspace's plugins do declare when none of them is it; null when
+ * there is no workspace; the load error when the workspace file could not
+ * say.
  */
 export async function resolvePluginCommand(
   verb: string,
   cwd = process.cwd(),
-): Promise<ResolvedPluginCommand | UnresolvedPluginCommand | null> {
+): Promise<ResolvedPluginCommand | NoPluginCommand | UnresolvedPluginCommand | null> {
   const ws = await workspacePlugins(cwd)
   if (ws === null) return null
   if ('loadError' in ws) return ws
+  const declaredVerbs = new Set<string>()
   for (const plugin of ws.plugins) {
+    for (const declared of Object.keys(plugin.commands ?? {})) declaredVerbs.add(declared)
     const command = plugin.commands?.[verb]
     if (command === undefined) continue
     return {
@@ -73,10 +88,9 @@ export async function resolvePluginCommand(
       },
     }
   }
-  return null
+  return { declaredVerbs: [...declaredVerbs] }
 }
 
-/** `vx help` lines for every plugin verb in the workspace around `cwd`. */
 /** The plugin verbs the workspace around `cwd` declares, in declaration order; none when it does not load. */
 export async function pluginVerbs(cwd = process.cwd()): Promise<string[]> {
   const ws = await workspacePlugins(cwd).catch(() => null)
@@ -87,6 +101,7 @@ export async function pluginVerbs(cwd = process.cwd()): Promise<string[]> {
   return [...verbs]
 }
 
+/** `vx help` lines for every plugin verb in the workspace around `cwd`. */
 export async function pluginCommandHelp(cwd = process.cwd()): Promise<string[]> {
   const ws = await workspacePlugins(cwd).catch(() => null)
   if (ws === null || 'loadError' in ws) return []

package/src/cli/run.ts

@@ -1,4 +1,4 @@
-import { appendFile } from 'node:fs/promises'
+import { appendFile, mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import { documentedFlags, seeHelp } from './help.js'
 import { defaultAffectedBase, findWorkspaceRoot } from '../workspace/index.js'
@@ -15,7 +15,13 @@ import {
 import type { ContinueMode } from '../graph/index.js'
 import { type CachePolicy, FULL_CACHE_POLICY, parseCachePolicy } from '../cache/index.js'
 import { findCwdProject, pickTask, resolveFilters } from './select.js'
-import { MAX_TIMEOUT_MS, parseDecimalInt, nearest, machineParallelism } from '../util/index.js'
+import {
+  MAX_TIMEOUT_MS,
+  isUserError,
+  parseDecimalInt,
+  nearest,
+  machineParallelism,
+} from '../util/index.js'
 import { formatGraphDot, formatPlanJson, formatPlanText } from './plan-format.js'
 
 export interface RunArgs {
@@ -359,11 +365,21 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
   if (out.dry !== undefined && out.graph !== undefined) {
     return { ...out, error: '--dry and --graph are mutually exclusive' }
   }
-  if (out.dry !== undefined && (out.summarize !== undefined || out.profile !== undefined)) {
-    return { ...out, error: '--dry skips execution; --summarize / --profile need a real run' }
+  // Every flag that promises a file or a section about the run: the
+  // planning branch returns before any of them is written, and
+  // `--report-file="$GITHUB_STEP_SUMMARY" --dry` exited 0 having written
+  // nothing (item 992).
+  const needsRun =
+    out.summarize !== undefined ||
+    out.profile !== undefined ||
+    out.report !== undefined ||
+    out.reportFile !== undefined
+  const runOnly = '--summarize / --profile / --report / --report-file need a real run'
+  if (out.dry !== undefined && needsRun) {
+    return { ...out, error: `--dry skips execution; ${runOnly}` }
   }
-  if (out.graph !== undefined && (out.summarize !== undefined || out.profile !== undefined)) {
-    return { ...out, error: '--graph skips execution; --summarize / --profile need a real run' }
+  if (out.graph !== undefined && needsRun) {
+    return { ...out, error: `--graph skips execution; ${runOnly}` }
   }
   return out
 }
@@ -415,14 +431,28 @@ export async function resolveRunOptions(
     }
   }
 
-  // `--affected[=<base>]` is sugar for `--filter '[<base>]'`. Merging
-  // it into the filter list means the same code path handles plain
-  // filter use, --affected alone, and the combo.
+  // `--affected[=<base>]` is sugar for `--filter '...[<base>]'`: the
+  // changed projects AND their dependents — what a CI gate must run, what
+  // the flag's name says, what the guides promised while the sugar was the
+  // changed-only `[<base>]` (item 287). `--filter '[<base>]'` stays the
+  // "only what I touched" form. Merging it into the filter list means the
+  // same code path handles plain filter use, --affected alone, and the combo.
+  // It goes FIRST: filters apply in argv order, and appended last it came
+  // after every `!` exclude, so `--affected --filter '!app'` still ran app
+  // (item 955). An include's place does not change a union.
   const filterStrings = [...parsed.filters]
   if (parsed.affected !== undefined) {
     const root = await findWorkspaceRoot(cwd)
-    const base = parsed.affected === '' ? await defaultAffectedBase(root) : parsed.affected
-    filterStrings.push(`[${base}]`)
+    let base = parsed.affected
+    if (base === '') {
+      try {
+        base = await defaultAffectedBase(root)
+      } catch (err) {
+        if (!isUserError(err)) throw err
+        return { error: err.message }
+      }
+    }
+    filterStrings.unshift(`...[${base}]`)
   }
 
   // Project scope applies to bare task names only. Anchored entries
@@ -560,7 +590,17 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       if (parsed.graph === '') {
         process.stdout.write(out)
       } else {
-        await Bun.write(parsed.graph, out)
+        // The graph is the command's one product, so a path it cannot write
+        // is exit 1, said in one line as the other output paths say theirs:
+        // a directory or an unreachable path printed a raw stack (item 993).
+        const target = path.resolve(cwd, parsed.graph)
+        try {
+          await Bun.write(target, out)
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err)
+          process.stderr.write(`vx run: failed to write graph to ${target}: ${message}\n`)
+          return 1
+        }
       }
     } else if (parsed.dry === 'json') {
       process.stdout.write(formatPlanJson(plan))
@@ -595,6 +635,9 @@ export async function runCmd(args: readonly string[]): Promise<number> {
         // same job also write to. Truncating it would silently destroy their
         // content, and would make replacing the documented `>>` recipe a
         // behaviour change rather than a drop-in.
+        // Its directory made first, as `--summarize`, `--profile` and
+        // `--graph` make theirs: `nr/r.md` failed alone of the four (item 993).
+        await mkdir(path.dirname(target), { recursive: true })
         await appendFile(target, md)
       } catch (err) {
         // Same contract as --summarize / --profile: the run already

package/src/cli/select.ts

@@ -1,5 +1,5 @@
 // What a run is asked to run: the projects a `--filter` selects, the
-// ones `--affected` touches (with the orphan-path owners), the project the
+// ones `--affected` touches (with the `workspaceFiles` owners), the project the
 // cwd sits in, and the interactive picker. Every read of the workspace
 // here goes through the staged load, so the answer is the run's.
 
@@ -7,9 +7,11 @@ import readline from 'node:readline/promises'
 import path from 'node:path'
 import {
   affectedProjects,
+  refIsHead,
   applyFilters,
   buildPackageGraph,
   findWorkspaceRoot,
+  type LoadReads,
   type FingerprintClaims,
   FROZEN_WITHOUT_LOCK,
   listProjects,
@@ -29,8 +31,8 @@ import { type CliLoadOptions, loadCliProjects, loadCliWorkspace } from './worksp
 
 /**
  * The projects whose tasks declare a `cache.inputs.workspaceFiles` glob
- * matching an ORPHAN changed path (one no project owns): `--affected`
- * selects them, since the glob is that task's input. Through the run
+ * matching a changed path, one inside another project included (item
+ * 954): `--affected` selects them, since the glob is that task's input. Through the run
  * path's staged load, so a glob a `project` plugin gave a config-less
  * package counts; evaluated live as a default run does, or read from the
  * lock as a `--frozen` run does. A load that fails drops to the config files that
@@ -40,7 +42,7 @@ import { type CliLoadOptions, loadCliProjects, loadCliWorkspace } from './worksp
 export async function workspaceGlobOwners(
   root: string,
   projects: readonly ProjectMeta[],
-  orphans: readonly string[],
+  changed: readonly string[],
   load: CliLoadOptions = {},
   stagedLoad: () => Promise<ReadonlyMap<string, ProjectEntry>> = () =>
     loadCliProjects(root, projects, 'all', load),
@@ -49,7 +51,7 @@ export async function workspaceGlobOwners(
     for (const task of Object.values(config.tasks ?? {})) {
       const globs = task.cache?.inputs?.workspaceFiles
       if (globs === undefined) continue
-      if (orphans.some((rel) => workspaceGlobsMatch(globs, rel))) return true
+      if (changed.some((rel) => workspaceGlobsMatch(globs, rel))) return true
     }
     return false
   }
@@ -104,10 +106,10 @@ async function workspaceFingerprintClaims(
   }
 }
 
-export async function loadWorkspaceProjects(cwd: string): Promise<ProjectMeta[]> {
-  const root = await findWorkspaceRoot(cwd)
-  const ws = await loadWorkspace(root)
-  return await listProjects(ws)
+async function loadWorkspaceProjects(cwd: string): Promise<ProjectMeta[]> {
+  const reads: LoadReads = new Map()
+  const root = await findWorkspaceRoot(cwd, reads)
+  return await listProjects(await loadWorkspace(root, reads))
 }
 
 export async function findCwdProject(cwd: string): Promise<string | null> {
@@ -180,7 +182,7 @@ export async function resolveFilters(
   const parsed = raw.map((r) => parseFilter(r, root))
   const walksGraph = parsed.some((f) => f.withDeps || f.withDependents || f.onlyDeps)
   // Every reader of the staged configs in this pass — the `pkg#task`
-  // edge walk, the `workspaceFiles` owners of an orphan path — shares
+  // edge walk, the `workspaceFiles` owners of a changed path — shares
   // ONE load, and the run reuses it (`RunOptions.staged`): the `project`
   // stage runs once per project per run.
   let stagedPromise: Promise<Map<string, ProjectEntry>> | undefined
@@ -207,8 +209,8 @@ export async function resolveFilters(
         workspaceRoot: root,
         since: f.gitSince,
         projects,
-        workspaceGlobOwners: (orphans) =>
-          workspaceGlobOwners(root, projects, orphans, load, stagedOnce),
+        workspaceGlobOwners: (changed) =>
+          workspaceGlobOwners(root, projects, changed, load, stagedOnce),
         fingerprintClaims: () => workspaceFingerprintClaims(root, projects, load),
       })
       affectedByFilter.set(f, names)
@@ -238,7 +240,15 @@ export async function resolveFilters(
     const includes = parsed.filter((f) => !f.negate)
     if (includes.length > 0 && includes.every((f) => f.gitSince !== undefined)) {
       const refs = includes.map((f) => f.gitSince).join(', ')
-      return { empty: `nothing affected since ${refs}` }
+      // A base that IS HEAD (a single-branch clone whose `origin/HEAD` is
+      // the branch under test) can never mark anything affected, and this
+      // exit-0 note was the only sign (CI persona, 2026-09-16). Say so.
+      const self = includes.find((f) => refIsHead(root, f.gitSince!))
+      const hint =
+        self === undefined
+          ? ''
+          : ` — ${self.gitSince} is HEAD itself: compare with the branch you merge into (--affected=origin/main) or the previous commit (--affected=HEAD~1)`
+      return { empty: `nothing affected since ${refs}${hint}` }
     }
     // One line, not a warning per pattern and then an error saying the same:
     // the patterns are in the error, and the nearest project name is the

package/src/cli/show.ts

@@ -7,11 +7,13 @@
 // Deliberately NOT the lock — vx-lock.json is already the frozen JSON.
 
 import type { ProjectConfig, TaskConfig } from '../config.js'
+import { declaredTask } from '../graph/index.js'
 import { seeHelp } from './help.js'
 import { nearMatches, relPosix, UserError } from '../util/index.js'
 import { loadCliProjects } from './workspace-config.js'
 import {
   findWorkspaceRoot,
+  type LoadReads,
   listProjects,
   loadWorkspace,
   type ProjectEntry,
@@ -51,8 +53,9 @@ export async function showCmd(args: readonly string[]): Promise<number> {
     process.stderr.write(`vx show: ${parsed.error}\n`)
     return 1
   }
-  const root = await findWorkspaceRoot(process.cwd())
-  const metas = await listProjects(await loadWorkspace(root))
+  const reads: LoadReads = new Map()
+  const root = await findWorkspaceRoot(process.cwd(), reads)
+  const metas = await listProjects(await loadWorkspace(root, reads))
   const byName = new Map(metas.map((m) => [m.name, m]))
 
   const hashAt = parsed.target?.indexOf('#') ?? -1
@@ -84,7 +87,9 @@ export async function showCmd(args: readonly string[]): Promise<number> {
   }
 
   if (bareTask) {
-    const declaring = [...projects.values()].filter((p) => p.config.tasks?.[projectName!])
+    const declaring = [...projects.values()].filter(
+      (p) => declaredTask(p.config, projectName!) !== undefined,
+    )
     if (declaring.length === 0) {
       const names = new Set<string>()
       for (const p of projects.values())
@@ -109,7 +114,7 @@ export async function showCmd(args: readonly string[]): Promise<number> {
     return 0
   }
 
-  const task = config?.tasks?.[taskName]
+  const task = declaredTask(config, taskName)
   if (task === undefined) {
     throw new UserError(
       `unknown task: "${meta.name}#${taskName}"${suggest(taskName, Object.keys(config?.tasks ?? {}))}`,