@vzn/vx 0.0.637 → 0.0.639

package/src/cli/watch.ts

@@ -38,12 +38,12 @@ import {
 import { CLOSED, fsClockNow, type WatchHandle, WatcherPool } from './watch-fs.js'
 import { ChangeJudge } from './watch-judge.js'
 import { type WatchCycle, watchCycle } from './watch-cycle.js'
-import { hangupIgnored, maskedLine, restartTimings } from '../util/index.js'
+import { hangupIgnored, maskedLine, restartTimings, sayNotice, sayLine } from '../util/index.js'
 import { sweepConfigs, watchedProjects } from './watch-set.js'
 
 /** One line for a watcher or re-read the OS refused; the loop goes on without it. */
 function sayCannot(what: string, err: unknown): void {
-  process.stderr.write(`vx watch: ${what}: ${err instanceof Error ? err.message : String(err)}\n`)
+  sayNotice('warn', 'vx watch', `${what}: ${err instanceof Error ? err.message : String(err)}`)
 }
 
 /** Wait this long after the last filesystem event before re-running. */
@@ -61,22 +61,17 @@ const DEBOUNCE_MAX_MS = 1_000
  * the help line and the completions, and a test holds the two together.
  */
 export function watchRefusal(parsed: RunArgs): string | null {
-  if (parsed.dry !== undefined || parsed.graph !== undefined) {
-    return 'vx watch: --dry / --graph are not supported in watch mode'
+  if (parsed.dry !== undefined) {
+    return 'vx watch: --dry is not supported in watch mode'
   }
-  if (parsed.summarize !== undefined || parsed.profile !== undefined) {
-    return 'vx watch: --summarize / --profile are not supported in watch mode (would overwrite per cycle)'
+  if (parsed.profile !== undefined) {
+    return 'vx watch: --profile is not supported in watch mode (would overwrite per cycle)'
   }
-  // All three format ONE run's result and are consumed by `runCmd` alone, so
-  // a watch loop silently ignored them. `--verbosity 0` is not rejected: it
+  // It formats ONE run's result and is consumed by `runCmd` alone, so a
+  // watch loop silently ignored it. `--verbosity 0` is not rejected: it
   // asks for the output watch already gives.
-  if (
-    parsed.report !== undefined ||
-    parsed.reportFile !== undefined ||
-    parsed.verbosity > 0 ||
-    parsed.format !== 'pretty'
-  ) {
-    return 'vx watch: --report / --report-file / --verbosity / --format are not supported in watch mode (they report a single run)'
+  if (parsed.verbosity > 0) {
+    return 'vx watch: --verbosity is not supported in watch mode (it reports a single run)'
   }
   return null
 }
@@ -84,18 +79,20 @@ export function watchRefusal(parsed: RunArgs): string | null {
 export async function watchCmd(args: readonly string[]): Promise<number> {
   const parsed = parseRunArgs(args, 'watch')
   if (parsed.error) {
-    process.stderr.write(`vx watch: ${parsed.error}${seeHelp('watch')}\n`)
+    sayNotice('error', 'vx watch', `${parsed.error}${seeHelp('watch')}`)
     return 1
   }
 
   const refused = watchRefusal(parsed)
   if (refused !== null) {
-    process.stderr.write(`${refused}\n`)
+    sayLine('error', refused, 'vx watch')
     return 1
   }
   if (parsed.tasks.length === 0) {
-    process.stderr.write(
-      `vx watch: missing task name (vx watch <task>, e.g. vx watch build)${seeHelp('watch')}\n`,
+    sayNotice(
+      'error',
+      'vx watch',
+      `missing task name (vx watch <task>, e.g. vx watch build)${seeHelp('watch')}`,
     )
     return 1
   }
@@ -103,11 +100,11 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   const cwd = process.cwd()
   const resolved = await resolveRunOptions(parsed, cwd, parsed.tasks, 'watch')
   if ('error' in resolved) {
-    process.stderr.write(`vx watch: ${resolved.error}\n`)
+    sayNotice('error', 'vx watch', resolved.error)
     return 1
   }
   if ('nothingSelected' in resolved) {
-    process.stderr.write(`vx watch: ${resolved.nothingSelected}\n`)
+    sayNotice('info', 'vx watch', resolved.nothingSelected)
     return 0
   }
   // The watch loop owns SIGINT/SIGTERM for its whole lifetime. A cycle's
@@ -216,7 +213,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   let refusedToStart = false
   initial.held = runOrchestrator(initial.cycle.opts).then(
     (run) => {
-      if (run.refused !== undefined) process.stderr.write(`vx watch: ${run.refused}\n`)
+      if (run.refused !== undefined) sayNotice('error', 'vx watch', run.refused)
       // A run that failed having run nothing refused to start: a requested
       // name no project declares (run() says which, with a "did you mean").
       // `vx run` exits 1 on it; `vx watch buidl` watched on, re-running the
@@ -227,8 +224,10 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
       return run.persistent
     },
     (err: unknown) => {
-      process.stderr.write(
-        `vx watch: cycle failed: ${err instanceof Error ? err.message : String(err)}\n`,
+      sayNotice(
+        'error',
+        'vx watch',
+        `cycle failed: ${err instanceof Error ? err.message : String(err)}`,
       )
       return undefined
     },
@@ -247,7 +246,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   // run's own refusal and its "did you mean".
   if (scope.length === 0 && !unlocked) {
     await held?.stop()
-    process.stderr.write(`vx watch: no projects in scope\n`)
+    sayNotice('error', 'vx watch', 'no projects in scope')
     return 1
   }
   await armLoop(undefined, held)
@@ -491,7 +490,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
             held = cycle.persistent
             // What this cycle did not take (a server whose task did not run).
             await before?.stop()
-            if (cycle.refused !== undefined) process.stderr.write(`vx watch: ${cycle.refused}\n`)
+            if (cycle.refused !== undefined) sayNotice('error', 'vx watch', cycle.refused)
             changes.lastCycle = { start, end: Date.now() }
           } catch (err) {
             // A re-run can fail catastrophically when the workspace
@@ -503,7 +502,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
             // is the canonical exit; we don't unilaterally abort here.
             // A config's own throw or a plugin's failure may quote a secret (L-11).
             const message = maskedLine(err instanceof Error ? err.message : String(err))
-            process.stderr.write(`vx watch: cycle failed: ${message}\n`)
+            sayNotice('error', 'vx watch', `cycle failed: ${message}`)
           }
         // After a failed cycle too: a package added with a config that does
         // not load yet fails its cycle, and unarmed, the fix to that config
@@ -622,6 +621,19 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     }
   }
   const stale = (dir: string): boolean => armedAs.get(dir) !== inodeOf(dir)
+  /** The projects the workspace-wide arm names an event by. */
+  let wide: readonly ProjectMeta[] = []
+  // The deepest, as a nested project's file is its own.
+  const ownerOf = (abs: string): ProjectMeta | undefined => {
+    let best: ProjectMeta | undefined
+    for (const proj of wide)
+      if (
+        abs.startsWith(proj.dir + path.sep) &&
+        (best === undefined || proj.dir.length > best.dir.length)
+      )
+        best = proj
+    return best
+  }
   /** The root arm: recursive when workspace-wide or the one stream, else the root's own files only. */
   let rootArm: WatchHandle = CLOSED
   let dotVxArm: WatchHandle = CLOSED
@@ -696,7 +708,13 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
               configImportFiles.includes(abs)
             )
               reread = true
-            trigger(`root ${filename}`, abs)
+            const owner = ownerOf(abs)
+            trigger(
+              owner === undefined
+                ? `root ${filename}`
+                : `${owner.name} ${path.relative(owner.dir, abs)}`,
+              abs,
+            )
           })
         : oneStream
           ? arm(workspaceRoot, true, streamEvent)
@@ -721,6 +739,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   // (it would cover every project + node_modules + caches). On macOS one
   // recursive stream at the root stands for all of them (`oneStream`).
   const armMode = (watched: readonly ProjectMeta[]): void => {
+    wide = workspaceWide ? watched : []
     if (!workspaceWide) {
       streamed = oneStream ? toStream(watched) : []
       const inStream = new Set(streamed.map((s) => s.proj))
@@ -797,12 +816,18 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     armAncestors()
   }
 
-  // Said once the loop is armed, and again after a cycle that re-read the
-  // watched set (a member came or went, the lock or a plugin changed).
+  // Said once, when the loop first arms: a re-arm repeated it after every
+  // cycle that re-read the watched set, between task rows. `debug.watch`
+  // says each arm on stderr, for whoever needs to see the set change.
   let lastTasks: number | undefined
+  const plural = (n: number, noun: string): string => `${n} ${noun}${n === 1 ? '' : 's'}`
   const sayWatching = (count: number): void => {
-    const tasks = lastTasks === undefined ? '' : ` · ${lastTasks} task${lastTasks === 1 ? '' : 's'}`
-    process.stdout.write(`watching ${count} project${count === 1 ? '' : 's'}${tasks}\n`)
+    const tasks = lastTasks === undefined ? '' : ` · ${plural(lastTasks, 'task')}`
+    process.stdout.write(`watching ${plural(count, 'project')}${tasks}\n`)
+  }
+  const debugArms = resolveSetting('debug.watch', undefined).value === true
+  const sayArmed = (count: number): void => {
+    if (debugArms) process.stderr.write(`vx watch: armed ${plural(count, 'project')}\n`)
   }
 
   const rearm = async (say = true): Promise<void> => {
@@ -854,7 +879,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     // A new arm proves delivery like the first ones: an edit in the new
     // project right after this cycle is seen, not lost in the gap.
     await pool.proved()
-    if (say) sayWatching(next.projects.length)
+    if (say) sayArmed(next.projects.length)
   }
 
   armMode(projects)
@@ -872,10 +897,18 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   // never heard `packages/` removed under `packages/a` (inotify did).
   const ancestorArms = new Map<string, WatchHandle>()
   let ancestorNames = new Map<string, Set<string>>()
+  /** Each project directory below the root as these arms first saw it (`inodeOf`). */
+  let heldDirs = new Map<string, string>()
   const armAncestors = (): void => {
     ancestorNames = new Map()
     const rootDir = path.resolve(workspaceRoot)
     const below = projectDirs.filter((d) => path.resolve(d) !== rootDir)
+    heldDirs = new Map(
+      below.flatMap((d) => {
+        const id = inodeOf(d)
+        return id === undefined ? [] : [[d, id]]
+      }),
+    )
     for (const base of [...below, ...importNames.keys()]) {
       let dir = path.dirname(base)
       let name = path.basename(base)
@@ -907,8 +940,13 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
           arm(dir, false, (filename) => {
             // A project's parent's `.gitignore` shapes what its keys read, as the root's does.
             if (!ancestorNames.get(dir)?.has(filename) && filename !== '.gitignore') return
-            reread = true
             const abs = path.join(dir, filename)
+            // A project directory still the one its arm holds is no change:
+            // its arm judges what is in it. macOS reports the directory's
+            // mtime here on every write at its top level, and a cycle's own
+            // write started the next (solid's `types`, M 2026-10-15).
+            if (heldDirs.get(abs) === (inodeOf(abs) ?? '')) return
+            reread = true
             trigger(path.relative(workspaceRoot, abs), abs)
           }),
         )
@@ -937,6 +975,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
 
   lastTasks = args.tasks()
   sayWatching(projects.length)
+  sayArmed(projects.length)
 
   return await new Promise<void>((resolve) => {
     const cleanup = async (): Promise<void> => {

package/src/cli/why.ts

@@ -9,14 +9,14 @@ import { flagHint, formatValue, seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
 import {
   cacheKeyDiff,
-  explainCacheKeyQuery as explainCacheKey,
+  explainCacheKey,
   inputWriters,
   latestRunId,
   rootCauses,
-  whyDidThisRerunQuery as whyDidThisRerun,
-  resolveRunId,
-} from '../orchestrator/index.js'
-import { MASKED, nearMatches, printable, UserError } from '../util/index.js'
+  whyDidThisRerun,
+} from '../history/index.js'
+import { resolveRunId } from '../orchestrator/index.js'
+import { MASKED, nearMatches, printable, refusal, UserError } from '../util/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import { findCwdProject } from './select.js'
 import { cliCacheDir, discoverCliProjects, parseCacheDirFlag } from './workspace-config.js'
@@ -145,6 +145,15 @@ async function resolveTarget(
     .all() as Array<{ project: string; task: string }>
   const ids = pairs.map((p) => `${p.project}#${p.task}`)
   const invoked = ids.length === 0 && db.query('SELECT 1 FROM invocations LIMIT 1').get() !== null
+  if (ids.length === 0 && !invoked) {
+    throw refusal(
+      { tone: 'info', headline: `no runs of ${target} yet`, fix: `vx run ${target}` },
+      {
+        code: 'VX_E_NO_HISTORY',
+        message: `vx why: no recorded runs for "${target}"${suggest(target, ids, invoked)}`,
+      },
+    )
+  }
   if (target.includes('#')) {
     throw new UserError(
       `vx why: no recorded runs for "${target}"${suggest(target, ids, invoked)}`,

package/src/cli/workspace-config.ts

@@ -7,7 +7,7 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import type { WorkspaceConfig } from '../config.js'
-import { UserError } from '../util/index.js'
+import { UserError, sayLine } from '../util/index.js'
 import {
   discoverProjects,
   loadProjects,
@@ -33,7 +33,7 @@ interface CliWorkspace {
 }
 
 export const warnToStderr = (message: string): void => {
-  process.stderr.write(`${message}\n`)
+  sayLine('warn', message)
 }
 
 export async function loadCliWorkspace(workspaceRoot: string): Promise<CliWorkspace> {

package/src/config.ts

@@ -62,12 +62,6 @@ export interface RunSettings {
    * default) skips its dependents, `always` runs them too.
    */
   continue?: 'never' | 'deps-ok' | 'always'
-  /** How long a task that ignores SIGTERM gets before SIGKILL. Omitted → `'2s'`. */
-  killGrace?: Duration
-  /** The bound on each plugin's end-of-run flush and teardown. Omitted → `'3s'`. */
-  teardownTimeout?: Duration
-  /** How long a persistent task may take to match `readyWhen` before vx says it waits. Omitted → `'10s'`. */
-  readyNotice?: Duration
   /**
    * Graph rules checked by `vx lock` and `vx lock --check`, never by a
    * run. Each is on

package/src/exec/executor.ts

@@ -142,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_RUN_KILL_GRACE`, 2 s) after the abort, then
+   * waits the kill grace (2 s) after the abort, then
    * settles the attempt without `execute` and abandons it (H-14).
    */
   readonly signal?: AbortSignal

package/src/exec/sandbox-runtime.ts

@@ -2332,7 +2332,7 @@ function outsideWritesHint(
     ? `${refused} The task has its own temp directory, empty at its start: write under ` +
       `$TMPDIR (os.tmpdir() in Node and Bun) instead of a fixed path.`
     : `${refused} If the task needs one, grant its directory, e.g. ` +
-      `\`allow: { write: [${jsString(`${spelled}/`)}] }\`.`
+      `\`allow: { write: [${jsString(spelled.endsWith('/') ? spelled : `${spelled}/`)}] }\`.`
   return { timestamp: new Date(), hint: true, line }
 }
 

package/src/exec/sandbox-violations.ts

@@ -578,7 +578,9 @@ export function refusedWritesOutside(
     if (v.path === undefined || !path.isAbsolute(v.path) || !write || reported(v)) continue
     if (!skip.some((s) => atOrUnder(v.path!, s))) paths.add(v.path)
   }
-  return [...paths]
+  // `mkdir -p ~/.cache/tool` is refused at each directory on its way;
+  // the one it wanted is the deepest.
+  return [...paths].filter((p) => ![...paths].some((q) => q !== p && atOrUnder(q, p)))
 }
 
 /**

package/src/graph/index.ts

@@ -8,6 +8,7 @@ export {
   parseDependencySpec,
   type DependencySpec,
 } from './dependency-spec.js'
+export { computeReverseDepCount } from './priorities.js'
 export {
   type ContinueMode,
   deadServerBehind,
@@ -16,8 +17,15 @@ export {
   RestoreDemoted,
   runGraph,
   type TaskOutcome,
-  type TaskStatus,
 } from './scheduler.js'
+export {
+  type CacheSource,
+  deriveCacheSource,
+  isCacheHit,
+  isPassStatus,
+  TASK_STATUSES,
+  type TaskStatus,
+} from './task-status.js'
 export {
   buildTaskGraph,
   checkGraph,

package/src/graph/priorities.ts

@@ -85,7 +85,7 @@ export function tieredReverseDepCount(
  * dependents only (`calculateReverseDeps` in
  * `packages/nx/src/tasks-runner/utils.ts`, read 2026-09-24).
  */
-export function computeReverseDepCount(nodes: Map<string, TaskNode>): Map<string, number> {
+export function computeReverseDepCount(nodes: ReadonlyMap<string, TaskNode>): Map<string, number> {
   // Exact transitive-dependent COUNTS need closure SETS (diamonds
   // double-count under naive summing). Set-of-strings closures are
   // O(N²) entries and took 8.5s on a 1090-package, 100-layer repo;

package/src/graph/scheduler.ts

@@ -13,6 +13,7 @@ import {
   type ScheduleStrategy,
 } from './priorities.js'
 import { isGroupTask, type TaskNode } from './task-graph.js'
+import type { TaskStatus } from './task-status.js'
 
 /**
  * Thrown by `execute` for a restore-tier task that turned out to have
@@ -29,19 +30,6 @@ export class RestoreDemoted extends Error {
   }
 }
 
-export type TaskStatus =
-  | 'success'
-  | 'cache-hit'
-  | 'cache-hit-remote'
-  | 'failed'
-  | 'skipped'
-  // A child killed by a shutdown signal (SIGINT/SIGTERM — e.g. Ctrl-C):
-  // the task never finished on its own terms, so it reverts to aborted —
-  // excluded from the tally and the run history. It still PROPAGATES like
-  // a failure (see `willSkip`): the child died mid-write, so its outputs
-  // are partial.
-  | 'aborted'
-
 /** What moved in a missed task's key since the last entry saved for it. */
 export interface InputChanges {
   /** How many components changed, appeared or went. 0: the same key, its entry gone. */
@@ -79,8 +67,8 @@ export interface TaskOutcome {
    * How long an `admit` policy held this task after it was ready with a
    * free worker — the wait the plugin, not the count gate, imposed. Set
    * only when a policy refused it at least once (so a run with no policy
-   * carries the field on no outcome); `--summarize` rows, the event
-   * stream and the summary footer show it.
+   * carries the field on no outcome); the event stream and the summary
+   * footer show it.
    */
   admissionHeldMs?: number
   /**
@@ -136,7 +124,7 @@ export interface TaskOutcome {
    * On a `skipped` outcome: the task at the ROOT of what blocked it — the
    * failed (or aborted) upstream, followed through any chain of skips
    * between. Absent when the skip was fail-fast's (no upstream failed).
-   * The footer, `--summarize`, the telemetry record and the run row all
+   * The footer, the telemetry record and the run row all
    * read this one field (item 267).
    */
   blockedBy?: string
@@ -152,6 +140,12 @@ export interface TaskOutcome {
    * bounded to its first 8 KiB and last 56 KiB. The run's history keeps it.
    */
   failedOutput?: string
+  /**
+   * When the run keeps its bytes in a remote, a task that ran and saved no
+   * entry (failed, or uncached): its whole output as `encodeOutputLog`
+   * stores it, secrets masked, at the entry's bounds.
+   */
+  runLog?: string
   /**
    * On a failed persistent task: why it never became ready — the readiness
    * deadline fired, the child exited first (`exitCode` is then its own), or
@@ -171,6 +165,8 @@ export interface TaskOutcome {
    *  (`--cache-download=none`) instead of landing on this machine. Absent for
    *  every ordinary outcome. Telemetry-only. */
   outputs?: 'deferred'
+  /** The task ran here and its result went to the cache. The footer's `↑`. */
+  saved?: true
   /**
    * v11 analytics: hrtime span relative to the parent run's t=0.
    * Lets downstream analytics reconstruct the actual parallel timeline