@vzn/vx 0.0.639 → 0.0.640

package/src/orchestrator/steps.ts

@@ -3,25 +3,45 @@
 // `:teardown`. `:` is no task id's separator, so a step never collides with
 // a project named `vx` or a plugin package's own `#setup` task. A step is
 // not a task: no stat, history row or telemetry record counts it.
+//
+// A run shows only the steps it waits on, before its first task or its end
+// (M, 2026-10-16). One that runs beside the tasks (`vx:prefetch`) is a
+// `background` step: never shown, and kept for `vx last` (run-steps.ts).
 import type { Logger } from '../report/index.js'
+import type { RunStep } from './run-steps.js'
 
 export interface Steps {
   /** Time `work` as step `id` when steps show; else run it as it is. */
   step<T>(id: string, work: () => Promise<T>): Promise<T>
   stepSync<T>(id: string, work: () => T): T
-}
-
-const unseen: Steps = {
-  step: (_id, work) => work(),
-  stepSync: (_id, work) => work(),
+  /** Time `work`, which the run does not wait on, as step `id` into `background`. */
+  background<T>(id: string, work: () => Promise<T>): Promise<T>
+  /** The background steps that have ended. */
+  readonly ended: readonly RunStep[]
 }
 
 /** Steps that tell `log`, or none when nothing renders them (zero cost). */
 export function createSteps(log: Logger, shown: boolean): Steps {
-  if (!shown) return unseen
+  const ended: RunStep[] = []
+  // Timed whether or not anything shows: only a run with a remote starts one.
+  const background = async <T>(id: string, work: () => Promise<T>): Promise<T> => {
+    const t0 = performance.now()
+    let ok = false
+    try {
+      const value = await work()
+      ok = true
+      return value
+    } finally {
+      ended.push({ id, durationMs: Math.round(performance.now() - t0), ok })
+    }
+  }
+  if (!shown)
+    return { step: (_id, work) => work(), stepSync: (_id, work) => work(), background, ended }
   const end = (id: string, t0: number, ok: boolean): void =>
     log.stepEnd?.(id, { durationMs: performance.now() - t0, ok })
   return {
+    background,
+    ended,
     async step(id, work) {
       const t0 = performance.now()
       log.stepStart?.(id)

package/src/orchestrator/task-hash.ts

@@ -1,6 +1,6 @@
 import { lstatSync } from 'node:fs'
 import path from 'node:path'
-import type { TaskConfig, CacheConfig } from '../config.js'
+import type { TaskConfig } from '../config.js'
 import type { ProjectFilesCache, WorkspaceFilesCache } from '../cache/index.js'
 import {
   ABSENT_INPUT,
@@ -85,11 +85,12 @@ export interface ComputeHashArgs {
  * previews.
  *
  * Caller is responsible for handling the group-task case before
- * calling this — groups have no `exec` and no `cache.inputs`, so the
+ * calling this — an unkeyed group has no `exec` and no `inputs`, so the
  * key-derivation steps below would all fall back to defaults.
  * `computeGroupKey` is exported for that purpose.
  */
 export async function computeTaskHash(args: ComputeHashArgs): Promise<string> {
+  if (isKeyless(args.node.config)) return keylessHash(args.node.id)
   const end = span('task hash')
   try {
     return await args.cache.key((await resolveKeyInput(args)).input)
@@ -98,6 +99,27 @@ export async function computeTaskHash(args: ComputeHashArgs): Promise<string> {
   }
 }
 
+/**
+ * A task that runs a command and declares no `inputs`: nothing says what
+ * it read, so no key can stand for its outputs, and a key that folds it
+ * would replay a stale entry (owner, 2026-10-16).
+ */
+export function isKeyless(task: TaskConfig): boolean {
+  return task.exec !== undefined && task.inputs === undefined
+}
+
+/**
+ * Drawn once per process, so no run derives another run's keyless keys;
+ * on first use, as the browser playground loads this module with no `crypto`.
+ */
+let keylessSalt: string | undefined
+
+/** A keyless task's key: this run's alone, so every key folding it misses. */
+function keylessHash(taskId: string): string {
+  keylessSalt ??= crypto.randomUUID()
+  return xxh3hex(`keyless\0${keylessSalt}\0${taskId}`)
+}
+
 /**
  * One file the key folded: the digest it folded, and since when (ms since
  * the epoch) that digest is known to be the file's content — the
@@ -250,14 +272,14 @@ async function resolveKeyInput(
   args: ComputeHashArgs,
 ): Promise<{ input: CacheKeyInput; listings: InputListing[] }> {
   const cfg = args.node.config
-  const cacheCfg: CacheConfig | undefined = cfg.cache
+  const cacheCfg = cfg.cache
   const outputs = cacheCfg?.outputs.files ?? []
 
   const resolved = await resolveInputs({
     projectDir: args.node.projectDir,
     workspaceRoot: args.workspaceRoot,
     envSource: process.env,
-    inputs: cacheCfg?.inputs,
+    inputs: cfg.inputs,
     ownOutputs: outputs,
     ownWorkspaceOutputs: cacheCfg?.outputs.workspaceFiles ?? [],
     nestedProjectDirs: args.nestedProjectDirs,
@@ -282,7 +304,7 @@ async function resolveKeyInput(
 
   const upstreamPairs = filterUpstreamHashes(
     args.upstream,
-    cacheCfg?.inputs?.tasks,
+    cfg.inputs?.tasks,
     args.node.projectName,
     args.node.id,
   )
@@ -290,7 +312,7 @@ async function resolveKeyInput(
   // hash → upstream task id, for capture-row naming only (not folded).
   const upstreamIds = new Map(upstreamPairs.map(([id, hash]) => [hash, id]))
   // The DEPENDENCY closure, groups expanded — for the executor's input root.
-  // Deliberately NOT the filtered set above: `cache.inputs.tasks` says which
+  // Deliberately NOT the filtered set above: `inputs.tasks` says which
   // upstream KEYS this task's key folds, and what a task may READ is
   // `dependsOn`. Locally every dependency's outputs are on disk before the
   // command runs however the filter is written, so an executor that ships the
@@ -306,7 +328,7 @@ async function resolveKeyInput(
   // also merge the workspace-wide partition's OIDs (keyed by abs
   // path, so the two maps agree wherever they overlap).
   let fileHashes = args.gitFilesCache?.oidsFor(args.node.projectDir)
-  if ((cacheCfg?.inputs.workspaceFiles?.length ?? 0) > 0) {
+  if ((cfg.inputs?.workspaceFiles?.length ?? 0) > 0) {
     const wsOids = args.gitFilesCache?.oidsFor(args.workspaceRoot)
     if (wsOids !== undefined && wsOids !== fileHashes) {
       fileHashes = fileHashes === undefined ? wsOids : new Map([...wsOids, ...fileHashes])
@@ -390,12 +412,12 @@ function hashableConfig(cfg: TaskConfig): unknown {
 }
 
 /**
- * A group's key: its upstream, and for a keyed group — one with `cache`,
+ * A group's key: its upstream, and for a keyed group — one with `inputs`,
  * the default `build` (projects.ts) or a config's — its own inputs too,
  * the way a task's key folds them.
  */
 export async function computeGroupKey(args: ComputeHashArgs): Promise<string> {
-  if (args.node.config.cache === undefined) return computeGroupHash(args.upstream)
+  if (args.node.config.inputs === undefined) return computeGroupHash(args.upstream)
   return computeTaskHash(args)
 }
 

package/src/orchestrator/telemetry-host.ts

@@ -27,8 +27,8 @@ import type { VxPlugin } from './plugin.js'
 export interface TelemetryHandle {
   /** Emit the per-run summary to every sink (crash-isolated). */
   emitSummary(summary: RunSummaryRecord): void
-  /** Await every sink's flush (crash-isolated, time-bounded by the sink). */
-  flush(): Promise<void>
+  /** Await every sink's flush (crash-isolated, time-bounded by the sink), each as a `<plugin>:telemetry` step. */
+  flush(step?: <T>(id: string, work: () => Promise<T>) => Promise<T>): Promise<void>
   /** Remove the bus subscription. Idempotent. */
   dispose(): void
   /** Sample a running task's process tree; see `TelemetrySource.track`. */
@@ -125,7 +125,7 @@ export async function subscribeTelemetry(
   const dispose = bus.subscribe(source.subscriber)
   return {
     emitSummary: (summary) => source.emitSummary(summary),
-    flush: () => source.flush(),
+    flush: (step) => source.flush(step),
     dispose,
     ...(source.track !== undefined ? { track: source.track } : {}),
   }

package/src/orchestrator/telemetry.ts

@@ -391,8 +391,11 @@ export interface TelemetrySource {
   readonly subscriber: RunEventSubscriber
   /** Fan the per-run summary to every sink's `onRunSummary` (crash-isolated). */
   emitSummary(summary: RunSummaryRecord): void
-  /** Await every sink's `flush()` (each crash-isolated, all time-bounded). */
-  flush(): Promise<void>
+  /**
+   * Await every sink's `flush()` (each crash-isolated, all time-bounded),
+   * each as the step `<plugin>:telemetry` through `step`.
+   */
+  flush(step?: <T>(id: string, work: () => Promise<T>) => Promise<T>): Promise<void>
   /**
    * Sample this task's process tree every `SAMPLE_MS` until the returned
    * function is called, the root exits, or the run ends. Present only when
@@ -625,7 +628,7 @@ export function createTelemetrySource(args: {
         }
       }
     },
-    async flush(): Promise<void> {
+    async flush(step = <T>(_id: string, work: () => Promise<T>): Promise<T> => work()) {
       const ms = teardownTimeoutMs()
       // Bounded, for the same reason plugin teardown is bounded in
       // plugin-host.ts: run() awaits this BEFORE closeCache() and before it
@@ -641,7 +644,9 @@ export function createTelemetrySource(args: {
           sinks.map(async (sink) => {
             if (disabled.has(sink) || sink.flush === undefined) return
             try {
-              await sink.flush(deadline.signal)
+              await step(`${args.owners?.get(sink) ?? label(sink)}:telemetry`, () =>
+                sink.flush!(deadline.signal),
+              )
             } catch (err) {
               // A flush failure can never break the run — but it still costs
               // this sink its export, so say so rather than dropping it.

package/src/orchestrator/upstream.ts

@@ -1,14 +1,9 @@
 import {
-  DependencySpecError,
-  compileTaskPattern,
-  isGroupTask,
-  isTaskPattern,
-  parseDependencySpec,
-  type DependencySpec,
+  selectFoldedDeps,
+  type FoldCandidate,
   type TaskNode,
   type TaskOutcome,
 } from '../graph/index.js'
-import { UserError } from '../util/index.js'
 
 /**
  * A task's upstream as its KEY reads it: the live outcomes of its scheduled
@@ -36,15 +31,9 @@ export function keyedOutcome(node: TaskNode, hash: string | undefined): TaskOutc
   return o
 }
 
-/** `node.deps` less its ordering-only edges: the dependencies a key may fold. */
-export function keyedDeps(node: TaskNode): readonly string[] {
-  const order = node.orderOnly
-  return order === undefined ? node.deps : node.deps.filter((d) => !order.includes(d))
-}
-
 /**
  * Pick which upstream task hashes participate in the current task's
- * cache key, filtered by `cache.inputs.tasks`. The folded value is the
+ * cache key, filtered by `inputs.tasks`. The folded value is the
  * upstream's own cache key (its input-based task hash) — pure-input
  * transitive hashing, like Turbo/Nx. An upstream change propagates
  * through its key into every dependent's key. There is deliberately NO
@@ -77,135 +66,6 @@ export function filterUpstreamHashes(
   ])
 }
 
-/**
- * A filter selects among the task's own dependencies, never through a
- * group: `dependsOn: ['build']` over a group `build` of `build.a` and
- * `build.b` offers the filter `build`, not its members. A pattern that
- * matches only a member (`build.*`) therefore selected nothing, and the key stopped moving
- * with that member's inputs: a stale hit under a green run. Such a spec
- * is refused, once, over the graph every key site reads. One that matches
- * nothing anywhere stays legal (a preset's pattern needn't match in every
- * project). An exact name is refused earlier, at load, unless `dependsOn`
- * names it (`assertFilterNamesDeclaredDeps`).
- */
-export function refuseFiltersThroughGroups(nodes: ReadonlyMap<string, TaskNode>): void {
-  for (const node of nodes.values()) {
-    const filter = node.config.cache?.inputs?.tasks
-    if (filter === undefined || filter.length === 0) continue
-    const deps = keyedDeps(node).flatMap((id) => nodes.get(id) ?? [])
-    const groups = deps.filter(isGroupTask)
-    if (groups.length === 0) continue
-    for (const raw of filter) {
-      const spec = parseSpec(raw, node.id)
-      if (spec.negated) continue
-      const matches = specMatcher(spec)
-      const hit = (n: TaskNode): boolean => matches(n, n.projectName === node.projectName)
-      if (deps.some(hit)) continue
-      for (const group of groups) {
-        const member = groupMembers(group, nodes).find(hit)
-        if (member === undefined) continue
-        throw new UserError(
-          `${node.id}: cache.inputs.tasks: '${raw}' matches ${member.id} only through the group ${group.id}, so it selects nothing; name '${group.taskName}' or depend on ${member.id} directly`,
-        )
-      }
-    }
-  }
-}
-
-function parseSpec(raw: string, selfTaskId: string): DependencySpec {
-  try {
-    return parseDependencySpec(raw)
-  } catch (err) {
-    if (err instanceof DependencySpecError) {
-      throw new UserError(`${selfTaskId}: cache.inputs.tasks: ${err.message}`)
-    }
-    throw err
-  }
-}
-
-/** Every task a group stands for, through nested groups, each once. */
-function groupMembers(group: TaskNode, nodes: ReadonlyMap<string, TaskNode>): TaskNode[] {
-  const out: TaskNode[] = []
-  const seen = new Set<string>([group.id])
-  const stack = group.deps.toReversed()
-  while (stack.length > 0) {
-    const id = stack.pop()!
-    if (seen.has(id)) continue
-    seen.add(id)
-    const n = nodes.get(id)
-    if (n === undefined) continue
-    out.push(n)
-    if (isGroupTask(n)) stack.push(...n.deps.toReversed())
-  }
-  return out
-}
-
-/**
- * One dependency as the key fold sees it: the task, and the value the
- * fold dedups by — its hash on the hash path, a structural stand-in for
- * the hash on the graph (`foldUnit` in keyed-projects.ts).
- */
-export interface FoldCandidate {
-  node: TaskNode
-  unit: string
-}
-
-/**
- * The dependencies a task's key folds, per its `cache.inputs.tasks`.
- *
- * Patterns (Turbo/Nx micro-syntax + filter extensions):
- *   '*'         all same-project upstream
- *   '^*'        all dep-workspace upstream
- *   'name'      same-project task `name`
- *   '^name'     `name` task in every dep workspace
- *   'pkg#name'  specific package's `name` task
- *   'name.*'    patterns — EITHER half of any form above may contain `*`
- *               (same glob as dependsOn patterns), including the project
- *               half of `pkg#name`. A filter that matched literally here
- *               would silently select ZERO upstream hashes and decouple the
- *               task from its dependencies — a stale-hit trap, so every
- *               name is matched through the shared glob.
- *   '!<form>'   exclude — any of the above with a leading `!`
- *
- * Patterns are applied in order; last write wins, so
- * `['*', '^*', '!^noisy']` reads as "all minus deps' noisy".
- *
- * Defaults:
- *   - `filter === undefined` → every candidate, as given.
- *   - `filter === []`        → none (fully decoupled).
- *
- * Otherwise deduped by `unit`, first candidate kept. The unit is the
- * fold's own identity, not the task's: two groups over the same members
- * share one hash, so excluding either excludes both, and a selection by
- * task id would keep the other while the key folded neither.
- */
-export function selectFoldedDeps(
-  deps: readonly FoldCandidate[],
-  filter: readonly string[] | undefined,
-  selfProjectName: string,
-  selfTaskId: string,
-): FoldCandidate[] {
-  if (filter === undefined) return [...deps]
-
-  const specs: DependencySpec[] = filter.map((raw) => parseSpec(raw, selfTaskId))
-
-  // Per-spec predicate, compiled once (exact compares + patterns).
-  const matchers = specs.map((spec) => specMatcher(spec))
-
-  const selected = new Map<string, FoldCandidate>()
-  for (let i = 0; i < specs.length; i++) {
-    const spec = specs[i]!
-    const matches = matchers[i]!
-    for (const d of deps) {
-      const isSelf = d.node.projectName === selfProjectName
-      if (!matches(d.node, isSelf)) continue
-      if (spec.negated) selected.delete(d.unit)
-      else if (!selected.has(d.unit)) selected.set(d.unit, d)
-    }
-  }
-  return [...selected.values()]
-}
-
 /**
  * Expand any GROUP among these outcomes into the real tasks it stands for,
  * transitively, preserving order and de-duplicating by task id.
@@ -223,7 +83,7 @@ export function selectFoldedDeps(
  * along two paths (a group `build` whose `^build` meets a package diamond)
  * is expanded once, or the walk doubles per layer. Only what the FILTER
  * already selected is passed in, so a group excluded from a task's
- * `cache.inputs.tasks` brings no members with it.
+ * `inputs.tasks` brings no members with it.
  */
 export function expandGroupUpstream(upstream: readonly TaskOutcome[]): TaskOutcome[] {
   const out: TaskOutcome[] = []
@@ -245,40 +105,3 @@ export function expandGroupUpstream(upstream: readonly TaskOutcome[]): TaskOutco
   }
   return out
 }
-
-/** Exact-name compare, or the shared `*`-glob when the name is a pattern. */
-function nameMatcher(name: string): (candidate: string) => boolean {
-  if (isTaskPattern(name)) {
-    const re = compileTaskPattern(name)
-    return (candidate) => re.test(candidate)
-  }
-  return (candidate) => candidate === name
-}
-
-/**
- * Compile one spec into an upstream predicate. BOTH halves of a `pkg#task`
- * form glob: a filter only ever selects from upstreams that already exist,
- * so a package pattern is unambiguous here — unlike dependsOn, which must
- * materialize concrete edges and therefore rejects it.
- */
-function specMatcher(spec: DependencySpec): (n: TaskNode, isSelf: boolean) => boolean {
-  switch (spec.kind) {
-    case 'wildcardSelf':
-      return (_n, isSelf) => isSelf
-    case 'wildcardDeps':
-      return (_n, isSelf) => !isSelf
-    case 'self': {
-      const task = nameMatcher(spec.task)
-      return (n, isSelf) => isSelf && task(n.taskName)
-    }
-    case 'deps': {
-      const task = nameMatcher(spec.task)
-      return (n, isSelf) => !isSelf && task(n.taskName)
-    }
-    case 'cross': {
-      const project = nameMatcher(spec.project)
-      const task = nameMatcher(spec.task)
-      return (n) => project(n.projectName) && task(n.taskName)
-    }
-  }
-}

package/src/report/framed-output.ts

@@ -532,7 +532,7 @@ function violationSection(outcome: TaskOutcome, colors: ColorSupport): string[]
           ...(fix.inputs !== undefined
             ? [
                 dim(
-                  `and, if the output depends on them, cache.inputs.files: [${fix.inputs.map((p) => `'${p}'`).join(', ')}]`,
+                  `and, if the output depends on them, inputs.files: [${fix.inputs.map((p) => `'${p}'`).join(', ')}]`,
                 ),
               ]
             : []),

package/src/report/status-line.ts

@@ -361,9 +361,13 @@ export function formatFailureLine(
   )
 }
 
+/** A step's cache column, dim as `no-cache` is. */
+const INTERNAL = 'internal'
+
 /**
  * The list row of one of vx's own steps (`vx:uploads`), on the task grid
- * with no cache column: a step is no task and caches nothing.
+ * with `internal` in the cache column: a step is no task and caches
+ * nothing (M, 2026-10-16: `4.60s success internal vx:keep-run`).
  */
 export function formatStepLine(
   id: string,
@@ -376,7 +380,7 @@ export function formatStepLine(
     durationMs,
     ok ? 'success' : 'failed',
     ok ? SUCCESS : ERROR,
-    '',
+    INTERNAL,
     '',
     paintPinnedId(id, colors),
     colors,
@@ -464,7 +468,7 @@ export function formatStatusRegion(
         Math.max(0, s.nowMs - step.startedMs),
         'running',
         ACCENT,
-        '',
+        INTERNAL,
         '',
         paintPinnedId(step.id, colors),
         colors,

package/src/settings.ts

@@ -108,12 +108,6 @@ export const SETTINGS: readonly Setting[] = [
     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' },
@@ -176,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' },
@@ -393,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/paths.ts

@@ -163,7 +163,7 @@ export function isLiteralPattern(glob: string): boolean {
 }
 
 /**
- * The alphabet of a TASK glob (`cache.inputs.files`, `cache.outputs.files`,
+ * The alphabet of a TASK glob (`inputs.files`, `cache.outputs.files`,
  * `workspaceFiles`), behind {@link isLiteralPattern}, for the callers that
  * need the POSITION of the first wildcard rather than a verdict. Every site
  * that asks "must this declaration be matched?" reads this one regex: item

package/src/workspace/affected.ts

@@ -6,7 +6,7 @@
 // index + unstaged — so it captures everything you touched and nothing
 // the base branch moved on with. Matches Turbo's `[<since>]` semantics.
 
-import { realpath } from 'node:fs/promises'
+import { realpath, stat } from 'node:fs/promises'
 import path from 'node:path'
 import {
   executablePath,
@@ -75,7 +75,7 @@ export interface AffectedArgs {
   since: string
   projects: readonly ProjectMeta[]
   /**
-   * Which projects declare a `cache.inputs.workspaceFiles` glob matching one of
+   * Which projects declare a `inputs.workspaceFiles` glob matching one of
    * these workspace-relative paths.
    *
    * A workspace-anchored glob is the documented escape hatch for inputs
@@ -107,6 +107,12 @@ export interface AffectedArgs {
    * run then paid again (I-26).
    */
   untracked?: () => Promise<readonly string[] | null>
+  /**
+   * The tracked symlinks, workspace-relative, from the run's enumeration
+   * (its index OIDs spell one `120000:`); null or absent spawns `git ls-files
+   * -s` here. A changed or untracked link is a changed path already.
+   */
+  links?: () => Promise<readonly string[] | null>
 }
 
 export interface FingerprintClaims {
@@ -253,6 +259,16 @@ export async function affectedChanges(
   const changed = [...diffed.paths, ...untracked.filter((s) => !isInstalledPath(s))].filter(
     (s) => s !== LOCKFILE_NAME,
   )
+  // A symlinked input keys the content behind it (cache/linked-inputs.ts),
+  // and the diff names that content's path, never the link's: a link whose
+  // target changed is a changed path itself.
+  changed.push(
+    ...(await linkedChanges(
+      args.workspaceRoot,
+      (await args.links?.().catch(() => null)) ?? (await trackedLinks(args.workspaceRoot)),
+      changed,
+    )),
+  )
   // The nested repositories git reports as one path: a gitlink, or an
   // untracked embedded repository (`dir/`, the only path git prints so).
   const nested = new Set(diffed.gitlinks)
@@ -503,6 +519,69 @@ async function bytesOrNull(file: string): Promise<Uint8Array | null> {
   return (await f.exists()) ? await f.bytes() : null
 }
 
+/** The symlinks the index lists, workspace-relative. */
+async function trackedLinks(workspaceRoot: string): Promise<string[]> {
+  const out: string[] = []
+  for (const record of await gitPaths(workspaceRoot, ['ls-files', '-s', '-z'])) {
+    if (record.startsWith('120000 ')) out.push(record.slice(record.indexOf('\t') + 1))
+  }
+  return out
+}
+
+/**
+ * The links in `links` whose target changed: a file `changed` names, or a
+ * directory holding one. A target git cannot diff is changed on every run:
+ * one outside the workspace, or git-ignored (or ignored files under a linked
+ * directory), since the key reads it whatever git says. A dangling link
+ * reads nothing; retargeting it is a change to the link itself.
+ */
+async function linkedChanges(
+  workspaceRoot: string,
+  links: readonly string[],
+  changed: readonly string[],
+): Promise<string[]> {
+  if (links.length === 0) return []
+  const realRoot = await realpath(workspaceRoot).catch(() => workspaceRoot)
+  const out: string[] = []
+  const inside: Array<{ link: string; target: string; dir: boolean }> = []
+  for (const link of links) {
+    let real: string
+    let dir: boolean
+    try {
+      real = await realpath(path.join(workspaceRoot, link))
+      dir = (await stat(real)).isDirectory()
+    } catch {
+      continue
+    }
+    const rel = path.relative(realRoot, real)
+    if (rel.startsWith('..') || path.isAbsolute(rel)) out.push(link)
+    else inside.push({ link, target: rel.split(path.sep).join('/'), dir })
+  }
+  if (inside.length === 0) return out
+  const named = inside.map((l) => l.target).filter((t) => t !== '')
+  const ignored = await gitPaths(workspaceRoot, [
+    'ls-files',
+    '--others',
+    '--ignored',
+    '--exclude-standard',
+    '--directory',
+    '-z',
+    '--',
+    ...(named.length === inside.length ? named : ['.']),
+  ])
+  const changedSet = new Set(changed)
+  const under = (p: string, dir: string): boolean => dir === '' || p.startsWith(`${dir}/`)
+  for (const { link, target, dir } of inside) {
+    const unseen = ignored.some((i) => {
+      const at = i.replace(/\/$/, '')
+      return at === target || under(target, at) || (dir && under(at, target))
+    })
+    const hit = dir ? changed.some((c) => under(c, target)) : changedSet.has(target)
+    if (unseen || hit) out.push(link)
+  }
+  return out
+}
+
 /** Run a NUL-separated path-listing git command from the workspace root. */
 async function gitPaths(workspaceRoot: string, cmd: string[]): Promise<string[]> {
   const proc = spawnGit([...cmd], workspaceRoot)

package/src/workspace/config-imports.ts

@@ -1,7 +1,7 @@
 // The third `changed file → project` channel for `--affected`.
 //
 // Directory containment answers "which project owns this file", and
-// `cache.inputs.workspaceFiles` answers "which project declared it". Neither
+// `inputs.workspaceFiles` answers "which project declared it". Neither
 // can see the one remaining way a file reaches a task: a project's
 // `vx.config.*` IMPORTS it. Resolved-config hashing folds the imported values
 // into the cache key (architecture principle #4), so editing such a file