@vzn/vx 0.0.651 → 0.0.653

package/src/history/metrics.ts

@@ -36,10 +36,11 @@ export interface RunSummaryRow {
   durationMs: number
   startedAt: number
   endedAt: number
+  /** Null: no cache outcome, a cached task whose hit failed to restore. */
   cacheHit: boolean | null
   /** On a hit: true when outputs were restored, false when up-to-date (v31); null otherwise. */
   restored: boolean | null
-  /** Whether the task declared a `cache` block; null on rows older than the column. */
+  /** Whether the task declared `cache: true`; null on rows older than the column. */
   cached: boolean | null
   hash: string
   cpuMs: number | null
@@ -382,7 +383,7 @@ export interface WhyDidThisRerun {
     cacheHit: boolean | null
     /** On a hit: outputs restored (true) or up-to-date (false); null otherwise. */
     restored: boolean | null
-    /** Whether the task declared a `cache` block; null on rows older than the column. */
+    /** Whether the task declared `cache: true`; null on rows older than the column. */
     cached: boolean | null
     startedAt: number
   }
@@ -409,6 +410,17 @@ function failedWithWrites(db: Database, id: string | null): number {
   return row !== null && writesCache(row.p) ? row.f : 0
 }
 
+const NO_WRITE = '--no-cache, or a --cache-policy without write'
+
+/** False only when the run's recorded policy writes no cache; an unrecorded one may have. */
+function runWritesCache(db: Database, id: string | null): boolean {
+  if (id === null) return true
+  const row = db.query('SELECT cache_policy AS p FROM invocations WHERE run_id = ?').get(id) as {
+    p: string
+  } | null
+  return row === null || writesCache(row.p)
+}
+
 /**
  * The endings an UNCHANGED cache key can have. A re-execution is told apart
  * by the evidence the index holds: every one used to blame `--no-cache` /
@@ -468,6 +480,22 @@ function unchangedKeyNote(
       return `cache key unchanged — the previous run on this key ran beside a failed task (${before} failed in it) and was not saved: a task run past a failed dependency (--continue) is never cached, so there was nothing to hit`
     }
   }
+  // A task that passed behind a dependency its run never recorded: the
+  // one `--exclude-dependencies` left out, keyed but not run, so nothing
+  // built on it was saved (excluded-keys.ts). Before the prune: a key this
+  // run saved named an eviction that never happened.
+  if (
+    (createdAt === undefined || createdAt >= this_.startedAt) &&
+    prev.status === 'success' &&
+    prev.cacheHit === 0 &&
+    prev.blockedBy !== null &&
+    prev.runId !== null &&
+    db
+      .query('SELECT 1 FROM runs WHERE run_id = ? AND project = ? AND task = ?')
+      .get(prev.runId, ...splitTaskId(prev.blockedBy)) === null
+  ) {
+    return `cache key unchanged — the previous run on this key built on a dependency it left out (${prev.blockedBy}, --exclude-dependencies), so it saved nothing and there was nothing to hit`
+  }
   if (createdAt !== undefined && createdAt >= this_.startedAt) {
     return 'cache key unchanged — no entry for this key was in the cache when it ran (pruned or evicted), so it executed and saved one'
   }
@@ -493,18 +521,6 @@ function unchangedKeyNote(
     if (prevPolicy !== undefined && !writesCache(prevPolicy)) {
       return 'cache key unchanged — the previous run on this key did not write the cache (--no-cache, or a --cache-policy without write), so there was nothing to hit'
     }
-    // A task that passed behind a dependency its run never recorded: the
-    // one `--exclude-dependencies` left out, keyed but not run, so nothing
-    // built on it was saved (excluded-keys.ts).
-    if (
-      prev.blockedBy !== null &&
-      prev.runId !== null &&
-      db
-        .query('SELECT 1 FROM runs WHERE run_id = ? AND project = ? AND task = ?')
-        .get(prev.runId, ...splitTaskId(prev.blockedBy)) === null
-    ) {
-      return `cache key unchanged — the previous run on this key built on a dependency it left out (${prev.blockedBy}, --exclude-dependencies), so it saved nothing and there was nothing to hit`
-    }
     return 'cache key unchanged — the previous run on this key executed but no entry for it is in the cache (its save failed, or it was pruned since), so there was nothing to hit'
   }
   return 'cache key unchanged — re-executed on the same key though this run read the cache; vx cannot name the cause'
@@ -614,10 +630,10 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
           // one's is new each run, so every dependent misses: "folded by
           // dependents" read as if they could hit.
           this_.keylessBy === null
-          ? 'this task declares no `cache` block — it runs on every invocation; its key is folded by dependents only'
+          ? 'this task declares no `cache: true` — it runs on every invocation; its key is folded by dependents only'
           : this_.keylessBy === taskId
-            ? 'this task declares no `cache` block — it runs on every invocation; it declares no `inputs` either, so each run derives a new key and every task that depends on it misses; declare its `inputs`'
-            : `this task declares no \`cache\` block — it runs on every invocation; its key includes ${this_.keylessBy}, which declares no \`inputs\`, so each run derives a new key and every task that depends on it misses; declare inputs on ${this_.keylessBy}`
+            ? 'this task declares no `cache: true` — it runs on every invocation; it declares no `inputs` either, so each run derives a new key and every task that depends on it misses; declare its `inputs` (and `outputs` with `cache: true` to cache it too)'
+            : `this task declares no \`cache: true\` — it runs on every invocation; its key includes ${this_.keylessBy}, which declares no \`inputs\`, so each run derives a new key and every task that depends on it misses; declare inputs on ${this_.keylessBy}`
         : this_.keylessBy !== null
           ? keylessNote(taskId, this_.keylessBy)
           : prev && prev.hash !== this_.hash
@@ -837,7 +853,13 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   // the failure, or the one that broke it).
   // So did one that passed beside a failed task (--continue).
   const tainted = isPassStatus(prev.status) && failedWithWrites(db, prev.runId) > 0
-  if (cur.length > 0 && old.length === 0 && (!isPassStatus(prev.status) || tainted)) {
+  // So did one whose run wrote no cache (--no-cache, a read-only policy).
+  const prevNoWrite = isPassStatus(prev.status) && !runWritesCache(db, prev.runId)
+  if (
+    cur.length > 0 &&
+    old.length === 0 &&
+    (!isPassStatus(prev.status) || tainted || prevNoWrite)
+  ) {
     const saved = db
       .query(
         `SELECT run_id AS runId, hash FROM runs
@@ -848,7 +870,12 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
       .get(project, task, this_.id) as { runId: string | null; hash: string } | undefined
     if (saved) {
       const { entries, unchangedCount } = diffKeyComponents(loadEntryInputs(db, saved.hash), cur)
-      const since = `run ${saved.runId}, the last that saved an entry (${tainted ? 'the previous run ran beside a failed task, so it was not saved' : `the previous run ended ${prev.status}`})`
+      const why = tainted
+        ? 'the previous run ran beside a failed task, so it was not saved'
+        : prevNoWrite
+          ? `the previous run did not write the cache: ${NO_WRITE}`
+          : `the previous run ended ${prev.status}`
+      const since = `run ${saved.runId}, the last that saved an entry (${why})`
       return {
         runId,
         taskId,
@@ -873,11 +900,15 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
     const unsaved =
       cur.length === 0 && !isPassStatus(this_.status)
         ? `this run ended ${this_.status}`
-        : old.length === 0 && !isPassStatus(prev.status)
-          ? `the previous run ended ${prev.status}`
-          : old.length === 0 && tainted
-            ? 'the previous run ran beside a failed task'
-            : null
+        : cur.length === 0 && !runWritesCache(db, runId)
+          ? `this run did not write the cache (${NO_WRITE})`
+          : old.length === 0 && !isPassStatus(prev.status)
+            ? `the previous run ended ${prev.status}`
+            : old.length === 0 && tainted
+              ? 'the previous run ran beside a failed task'
+              : old.length === 0 && prevNoWrite
+                ? `the previous run did not write the cache (${NO_WRITE})`
+                : null
     return {
       runId,
       taskId,
@@ -889,7 +920,7 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
         this_.cached === 0
           ? // The verdict already says the task is uncached; this line says
             // why no input can be named.
-            'with no `cache` block it saves no entry, so no input fingerprints are kept to say which of its `inputs` moved its key; with no `inputs`, every run gives it a new key'
+            'without `cache: true` it saves no entry, so no input fingerprints are kept to say which of its `inputs` moved its key; with no `inputs`, every run gives it a new key'
           : unsaved !== null
             ? `cache key changed but input fingerprints are unavailable — ${unsaved} and saved no entry; only the key change is known`
             : 'cache key changed but input fingerprints are unavailable — the entry was pruned (or the row predates the `cached` column); only the key change is known',
@@ -924,18 +955,67 @@ export function upstreamTask(name: string): string {
   return i < 0 ? name : name.slice(i + GROUP_VIA.length)
 }
 
+/**
+ * The tasks `runId` recorded a row for, as `project#task`. One read: runs
+ * has no (project, task) index (schema.ts), so asking per task scans the
+ * run's rows each time, and a 10,000-task fan-in asked 10,000 times.
+ */
+export function recordedTasks(db: Database, runId: string): Set<string> {
+  const rows = db.query('SELECT project, task FROM runs WHERE run_id = ?').all(runId) as {
+    project: string
+    task: string
+  }[]
+  return new Set(rows.map((r) => `${r.project}#${r.task}`))
+}
+
 export interface RootCause {
-  /** From the asked task down to the one whose own inputs moved. */
-  chain: string[]
-  entries: CacheKeyDiff['entries']
+  /**
+   * From the asked task down to the one whose own inputs moved. Built on
+   * each read, as long as the chain: a deep graph has as many roots as
+   * tasks, so read it only for a root that is shown.
+   */
+  readonly chain: string[]
+  /** The task whose own inputs moved: the chain's last id. */
+  readonly task: string
+  readonly entries: CacheKeyDiff['entries']
+}
+
+/** A visited task: the step that reached it (`group ← task` through a group) and the visit it came from. */
+interface Reach {
+  readonly up: Reach | null
+  readonly step: readonly string[]
+}
+
+class Cause implements RootCause {
+  constructor(
+    private readonly reach: Reach,
+    readonly task: string,
+    readonly entries: CacheKeyDiff['entries'],
+  ) {}
+
+  get chain(): string[] {
+    const steps: (readonly string[])[] = []
+    for (let r: Reach | null = this.reach; r !== null; r = r.up) steps.push(r.step)
+    return steps.reverse().flat()
+  }
+
+  /** `--format json`'s root: its chain and entries, as before the back links. */
+  toJSON(): { chain: string[]; entries: CacheKeyDiff['entries'] } {
+    return { chain: this.chain, entries: this.entries }
+  }
 }
 
 /**
  * The tasks under `taskId`'s moved upstreams whose OWN key components
- * moved in the same run, each with the chain that carried it up. A task
- * visited once is not walked again (a diamond names its root once). A
- * group records no run, so `groups` (group id → the tasks it gathers)
- * carries the walk through it.
+ * moved, each with the chain that carried it up. An upstream is diffed
+ * between the two keys its dependant folded (the upstream row's before
+ * and after hashes), not against its own previous run, which names what
+ * moved since a run of it alone in between. A task visited once is not
+ * walked again (a diamond names its root once). A group records no run,
+ * so `groups` (group id → the tasks it gathers) carries the walk through
+ * it. Depth first, on a stack of its own: a 20,000-task chain is deeper
+ * than recursion goes, and each visit keeps only a link to the one that
+ * reached it, so no chain is copied per level.
  */
 export function rootCauses(
   db: Database,
@@ -944,32 +1024,50 @@ export function rootCauses(
   entries: CacheKeyDiff['entries'],
   groups: ReadonlyMap<string, readonly string[]> = new Map(),
 ): RootCause[] {
+  const recorded = recordedTasks(db, runId)
   const roots: RootCause[] = []
   const seen = new Set([taskId])
-  const walk = (chain: string[], moved: CacheKeyDiff['entries']): void => {
-    for (const e of moved) {
-      if (e.kind !== 'upstream') continue
-      const task = upstreamTask(e.name)
-      if (seen.has(task)) continue
-      seen.add(task)
-      const next = [...chain, ...e.name.split(GROUP_VIA)]
-      const d = cacheKeyDiff(db, runId, task)
-      // A group: its members carry the walk, named in the key through it
-      // (`group ← task`) or, in a row that names the group alone, by the graph.
-      if (!d.found) {
-        const members = groups.get(task) ?? []
-        walk(
-          next,
-          members.map((name) => ({ ...e, name })),
-        )
-        continue
-      }
-      const own = d.entries.filter((x) => x.kind !== 'upstream')
-      if (own.length > 0) roots.push({ chain: next, entries: own })
-      walk(next, d.entries)
+  const stack = [{ from: { up: null, step: [taskId] } as Reach, moved: entries, i: 0 }]
+  while (stack.length > 0) {
+    const frame = stack.at(-1)!
+    const { moved } = frame
+    if (frame.i === moved.length) {
+      stack.pop()
+      continue
+    }
+    const e = moved[frame.i++]!
+    if (e.kind !== 'upstream') continue
+    const task = upstreamTask(e.name)
+    if (seen.has(task)) continue
+    seen.add(task)
+    const reach: Reach = { up: frame.from, step: e.name.split(GROUP_VIA) }
+    if (!recorded.has(task)) {
+      // A group: its members carry the walk, by their own rows named
+      // through it (`group ← task`) when the key has them, else by the
+      // graph, whose members carry none of the dependant's keys.
+      const via = `${e.name}${GROUP_VIA}`
+      if (moved.some((x) => x.kind === 'upstream' && x.name.startsWith(via))) continue
+      const members = groups.get(task) ?? []
+      stack.push({
+        from: reach,
+        moved: members.map((name) => ({ ...e, name, before: null, after: null })),
+        i: 0,
+      })
+      continue
     }
+    let d: CacheKeyDiff['entries']
+    if (e.before !== null && e.after !== null) {
+      const before = loadEntryInputs(db, e.before)
+      const after = loadEntryInputs(db, e.after)
+      // A pruned or unsaved side kept no fingerprints: nothing to name.
+      d = before.length > 0 && after.length > 0 ? diffKeyComponents(before, after).entries : []
+    } else {
+      d = cacheKeyDiff(db, runId, task).entries
+    }
+    const own = d.filter((x) => x.kind !== 'upstream')
+    if (own.length > 0) roots.push(new Cause(reach, task, own))
+    stack.push({ from: reach, moved: d, i: 0 })
   }
-  walk([taskId], entries)
   return roots
 }
 
@@ -994,43 +1092,65 @@ const WRITE_SLACK_MS = 5
  * that writes a file another key reads re-keys that task on every run.
  * The file's mtime against the recorded windows, so
  * a writer that runs each time is named from its latest run, and an
- * edit made outside a run names none.
+ * edit made outside a run, or after run `runId` ended, names none.
  */
 export function inputWriters(
   db: Database,
+  runId: string,
   workspaceRoot: string,
   taskId: string,
   entries: CacheKeyDiff['entries'],
   roots: readonly RootCause[],
 ): InputWriter[] {
+  // Bounded on both sides by the longest recorded window, so the query
+  // walks `runs_started_at` over that span, not every older row.
   const during = db.query(
-    `SELECT project, task FROM runs
-      WHERE started_at <= ?1 + ${WRITE_SLACK_MS} AND ended_at >= ?1 - ${WRITE_SLACK_MS}
-        AND status != 'skipped'
+    `SELECT project, task FROM main.runs
+      WHERE started_at BETWEEN ?1 - ?2 - ${WRITE_SLACK_MS} AND ?1 + ${WRITE_SLACK_MS}
+        AND ended_at >= ?1 - ${WRITE_SLACK_MS} AND status != 'skipped'
       GROUP BY project, task ORDER BY MIN(started_at) LIMIT 3`,
   )
+  let bounds: { longest: number; runEnd: number } | undefined
+  // A deep graph has as many roots as tasks, most reading the same files:
+  // each file is stat'd and asked about once.
+  const byFile = new Map<string, string[] | null>()
+  const writersOf = (file: string): string[] | null => {
+    let w = byFile.get(file)
+    if (w !== undefined) return w
+    w = null
+    let mtime: number | undefined
+    try {
+      mtime = statSync(path.join(workspaceRoot, file)).mtimeMs
+    } catch {}
+    if (mtime !== undefined && bounds === undefined) {
+      const b = db
+        .query(
+          `SELECT (SELECT MAX(ended_at - started_at) FROM main.runs WHERE status != 'skipped') AS ms,
+                  (SELECT MAX(r.ended_at) FROM main.runs r JOIN main.run_ids k ON k.id = r.run
+                    WHERE k.run_id = ?1) AS runEnd`,
+        )
+        .get(runId) as { ms: number | null; runEnd: number | null }
+      bounds = { longest: b.ms ?? 0, runEnd: b.runEnd ?? 0 }
+    }
+    // A change after the asked run ended came after its tasks read the
+    // file: it says nothing about who wrote what they saw.
+    if (mtime !== undefined && mtime <= bounds!.runEnd + WRITE_SLACK_MS) {
+      const rows = during.all(mtime, bounds!.longest) as { project: string; task: string }[]
+      if (rows.length > 0) w = rows.map((r) => `${r.project}#${r.task}`)
+    }
+    byFile.set(file, w)
+    return w
+  }
   const out: InputWriter[] = []
   const owners = [
     { taskId, entries },
-    ...roots.map((r) => ({ taskId: r.chain.at(-1)!, entries: r.entries })),
+    ...roots.map((r) => ({ taskId: r.task, entries: r.entries })),
   ]
   for (const owner of owners) {
     for (const e of owner.entries) {
       if (e.kind !== 'file' || e.change === 'removed') continue
-      let mtime: number
-      try {
-        mtime = statSync(path.join(workspaceRoot, e.name)).mtimeMs
-      } catch {
-        continue
-      }
-      const rows = during.all(mtime) as { project: string; task: string }[]
-      if (rows.length > 0) {
-        out.push({
-          taskId: owner.taskId,
-          file: e.name,
-          writers: rows.map((r) => `${r.project}#${r.task}`),
-        })
-      }
+      const writers = writersOf(e.name)
+      if (writers !== null) out.push({ taskId: owner.taskId, file: e.name, writers })
     }
   }
   return out

package/src/index.ts

@@ -41,9 +41,10 @@ export type {
   TaskConfig,
   ExecConfig,
   ExecEnv,
-  CacheConfig,
   InputsConfig,
-  CacheOutputs,
+  TaskOutputs,
+  WorkspaceInputs,
+  WorkspaceOutputs,
   InputStability,
   SandboxConfig,
   SandboxGrants,
@@ -94,7 +95,8 @@ export { criticalPath, outputsOverlap, splitTaskId, taskDefinitions } from './gr
 export type { TaskNode, TaskOutcome, TaskStatus } from './graph/index.js'
 
 // Cache classes + the layer interface (the `cache` capability's currency).
-export { Cache } from './cache/index.js'
+// A remote layer errors a body it refuses with `CorruptArtifactError`.
+export { Cache, CorruptArtifactError } from './cache/index.js'
 export type {
   CacheLayer,
   PluginCache,
@@ -245,6 +247,7 @@ export type {
   ServerSpec,
   TaskExecutor,
   TaskPlacement,
+  WorkerAdvice,
 } from './exec/index.js'
 
 // Telemetry — THE canonical, versioned data-export contract every exporter

package/src/orchestrator/admission.ts

@@ -23,7 +23,7 @@ import type { CachePolicy } from '../cache/index.js'
 import { isGroupTask, RestoreDemoted, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import { executeTask, type ExecuteArgs } from './execute-task.js'
 import type { ShortCircuit } from './local-shortcircuit.js'
-import { computeTaskHash, type ComputeHashArgs } from './task-hash.js'
+import { computeTaskHash, type ComputeHashArgs, keyOf } from './task-hash.js'
 
 /** What `taintTracker` answers per dispatch, and what it learns per finish. */
 export interface TaintTracker {
@@ -52,7 +52,8 @@ const UNTAINTED: TaintTracker = {
  * Records which tasks ran behind a failure, or on the key of a dependency
  * that did not run (`seeds`), and answers, per task, whether this one does.
  * Disabled (always `false`, nothing recorded) unless the run's
- * `continueMode` is `'always'` or there is a seed.
+ * `continueMode` is `'always'`, there is a seed, or one may be added while
+ * the run goes on (`seedsLater`: a server that dies under a running task).
  *
  * A task's taint is read from its deps' SETTLED outcomes, not from what it
  * saw at dispatch: a restore-tier hit dispatches before its deps settle,
@@ -67,8 +68,9 @@ export function taintTracker(
   continueAlways: boolean,
   seeds: ReadonlySet<string>,
   nodes: ReadonlyMap<string, TaskNode>,
+  seedsLater = false,
 ): TaintTracker {
-  if (!continueAlways && seeds.size === 0) return UNTAINTED
+  if (!continueAlways && seeds.size === 0 && !seedsLater) return UNTAINTED
   const outcomes = new Map<string, TaskOutcome>()
   const memo = new Map<string, boolean>()
   const causes = new Map<string, string>()
@@ -186,7 +188,7 @@ export function admitTasks(
     const cacheable =
       !isGroupTask(node) &&
       node.config.exec?.persistent === undefined &&
-      node.config.cache !== undefined &&
+      node.config.cache === true &&
       canRead &&
       canWrite
     // A restore-tier task (confirmed local hit, may run before its deps)
@@ -206,12 +208,14 @@ export function admitTasks(
       return executeTask(buildExecuteArgs(node, upstream)).catch(dropProbe)
     }
     const { nestedDirsByProject, ...rest } = hashArgs
-    const hash = await computeTaskHash({
-      ...rest,
-      node,
-      upstream,
-      nestedProjectDirs: nestedDirsByProject.get(node.projectName) ?? [],
-    })
+    const hash = await keyOf(
+      computeTaskHash({
+        ...rest,
+        node,
+        upstream,
+        nestedProjectDirs: nestedDirsByProject.get(node.projectName) ?? [],
+      }),
+    )
     // Join a sibling already computing this exact task: wait, then
     // executeTask cache-hits on the artifact it just saved. A sibling that
     // saved nothing (it failed) leaves this task to run, so the joiners

package/src/orchestrator/affected-tasks.ts

@@ -27,6 +27,7 @@ import { applyGraphStage } from './graph-stage.js'
 import { hasHook } from './plugin-host.js'
 import type { VxPlugin } from './plugin.js'
 import { isDefaultBuild } from '../graph/index.js'
+import { relPosix } from '../util/index.js'
 
 /** Every file in this set re-keys each of its project's tasks, whatever their inputs. */
 const KEYED_BY_EVERY_TASK: ReadonlySet<string> = new Set(PROJECT_CONFIG_FILENAMES)
@@ -51,9 +52,10 @@ function wholeProjects(
       (t) => t.exec !== undefined && t.inputs !== undefined,
     )
     const links = changes.dirLinksIn?.get(name)
+    const loose = changes.untrackedIn?.get(name)
     const unclaimed = (rel: string): boolean =>
       KEYED_BY_EVERY_TASK.has(rel) ||
-      (!byKeys && !keyed.some((t) => declaresInput(t, rel, null, links?.has(rel))))
+      (!byKeys && !keyed.some((t) => declaresInput(t, rel, null, links?.has(rel), loose?.has(rel))))
     const rel = rels.find(unclaimed)
     if (rel !== undefined) whole.set(name, rel)
   }
@@ -78,11 +80,12 @@ export interface AffectedReason {
   file?: string
   project?: string
   via?: string[]
+  /** `workspace`: the file reached every project. The text label's, never on the JSON wire. */
+  wide?: true
 }
 
 /** Collects each kept task's `AffectedReason` when given; a run without one pays nothing. */
 export interface AffectedExplain {
-  workspaceRoot: string
   reasons: Map<string, AffectedReason>
 }
 
@@ -101,6 +104,7 @@ export function affectedRoots(
   changes: AffectedChanges,
   projects: ReadonlyMap<string, ProjectEntry>,
   packageGraph: PackageGraph,
+  workspaceRoot: string,
   explain?: AffectedExplain,
   /** Only what moves a key: a changed path no task declares reaches no task. */
   byKeys = false,
@@ -111,9 +115,12 @@ export function affectedRoots(
   const inProject = (name: string, rel: string | undefined): AffectedReason => {
     if (rel === undefined) {
       const file = changes.wholeBy?.get(name)
-      return file === undefined ? { kind: 'project' } : { kind: 'workspace', file }
+      if (file === undefined) return { kind: 'project' }
+      return changes.wide === true
+        ? { kind: 'workspace', file, wide: true }
+        : { kind: 'workspace', file }
     }
-    const dir = path.relative(explain!.workspaceRoot, projects.get(name)!.dir)
+    const dir = path.relative(workspaceRoot, projects.get(name)!.dir)
     return { kind: 'project', file: dir === '' ? rel : path.posix.join(dir, rel) }
   }
   // The builder's `^name` walk (task-graph.ts), keeping only the packages
@@ -134,7 +141,9 @@ export function affectedRoots(
         if (visited.has(target)) continue
         visited.add(target)
         if (holds(target)) continue
-        if (changes.projects.has(target)) {
+        // A loaded project without the task folds nothing into the key; the
+        // holders past it seed as nodes of their own.
+        if (!projects.has(target) && changes.projects.has(target)) {
           seeds?.set(n.id, { kind: 'package', project: target })
           return true
         }
@@ -149,9 +158,12 @@ export function affectedRoots(
     // Asked of every node, not only the changed projects' (the
     // `workspaceFiles` owners): a `graph` hook may have given the glob.
     if (keyed) {
-      const file = changes.changed.find((rel) =>
-        declaresInput(task, null, rel, changes.dirLinks?.has(rel)),
-      )
+      let projectDir: string | undefined
+      const file = changes.changed.find((rel) => {
+        const untracked = changes.untracked?.has(rel) === true
+        if (untracked) projectDir ??= relPosix(workspaceRoot, n.projectDir)
+        return declaresInput(task, null, rel, changes.dirLinks?.has(rel), untracked, projectDir)
+      })
       const dir =
         file === undefined
           ? (changes.nested ?? []).find((d) => workspaceFilesReachInto(task, d))
@@ -176,7 +188,8 @@ export function affectedRoots(
       return true
     }
     const links = changes.dirLinksIn?.get(n.projectName)
-    const rel = rels.find((r) => declaresInput(task, r, null, links?.has(r)))
+    const loose = changes.untrackedIn?.get(n.projectName)
+    const rel = rels.find((r) => declaresInput(task, r, null, links?.has(r), loose?.has(r)))
     if (rel === undefined) return false
     if (seeds !== null) seeds.set(n.id, { ...inProject(n.projectName, rel), kind: 'input' })
     return true
@@ -245,11 +258,14 @@ export function keptByAffected<R extends { project: string; task: string }>(
   changes: AffectedChanges,
   projects: ReadonlyMap<string, ProjectEntry>,
   packageGraph: PackageGraph,
+  workspaceRoot: string,
   keep: { named?: ReadonlySet<string>; outright?: ReadonlySet<string> } = {},
   explain?: AffectedExplain,
 ): R[] {
   const ids = requested.map((r) => `${r.project}#${r.task}`)
-  const reached = new Set(affectedRoots(nodes, ids, changes, projects, packageGraph, explain))
+  const reached = new Set(
+    affectedRoots(nodes, ids, changes, projects, packageGraph, workspaceRoot, explain),
+  )
   return requested.filter((r, i) => {
     const id = ids[i]!
     const why: AffectedReason['kind'] | null =
@@ -291,8 +307,14 @@ export async function affectedTaskProjects(args: {
     rules: args.rules,
   })
   if (hasHook(args.plugins, 'graph')) await applyGraphStage(args.plugins, nodes, args)
-  const kept = keptByAffected(nodes, requested, args.changes, args.projects, args.packageGraph, {
-    outright: new Set(args.outright),
-  })
+  const kept = keptByAffected(
+    nodes,
+    requested,
+    args.changes,
+    args.projects,
+    args.packageGraph,
+    args.workspaceRoot,
+    { outright: new Set(args.outright) },
+  )
   return kept.map((r) => r.project)
 }

package/src/orchestrator/command-windows.ts

@@ -1,6 +1,7 @@
-// When each command of the run ran and where it may write, so
-// `inputStability.strategy: 'mutable'` can tell a task's own identical
-// rewrite from another task's write and restore (STATUS item 28): a file
+// When each command of the run ran, and each restore or deferred fetch, and where it
+// may write, so `inputs.stability.strategy: 'mutable'` can tell a task's
+// own identical rewrite from another task's write and restore (STATUS item
+// 28), and `vx watch` a user's write from the run's own: a file
 // whose bytes match the key after a write is the task's own only if no
 // other command that may write it ran between the describe and that write.
 
@@ -16,7 +17,7 @@ interface Window {
 }
 
 export interface CommandWindows {
-  /** A command starts; the returned function marks its end. A server never calls it. */
+  /** A command, a hit's restore or a deferred fetch starts; the returned function marks its end. A server never calls it. */
   open(id: string, projectDir: string, reach: WriteReach): () => void
   /** Another command that may write `file` and ran at some point in [from, to]. */
   writerDuring(self: string, file: string, from: number, to: number): string | undefined
@@ -30,7 +31,9 @@ export function commandWindows(): CommandWindows {
       const w: Window = { id, projectDir, reach, from: Date.now(), to: Infinity }
       windows.push(w)
       return () => {
-        w.to = Date.now()
+        // `Date.now()` floors to the ms and a ctime does not: the command's
+        // last write can be stamped up to a millisecond past it.
+        w.to = Date.now() + 1
       }
     },
     writerDuring(self, file, from, to) {