@vzn/vx 0.0.635 → 0.0.637

package/src/orchestrator/run.ts

@@ -3,7 +3,7 @@
 // so the layers can be swapped without touching the others.
 
 import type { ProjectEntry } from '../workspace/index.js'
-import { loadWorkspace, unreachedHint, unreachedPackages } from '../workspace/index.js'
+import { inputStabilityEnv, LOCK_INVALID, lockEntryBroken } from '../workspace/index.js'
 import { realpathSync } from 'node:fs'
 import path from 'node:path'
 import {
@@ -37,8 +37,6 @@ import {
   stageTimes,
   killGraceMs,
   MAX_TIMEOUT_MS,
-  parseDuration,
-  parseSize,
   printTimings,
   ulid,
   isLiteralPattern,
@@ -49,10 +47,11 @@ import {
   teardownTimeoutMs,
   secretMask,
   isFsRefusal,
+  isUserError,
 } from '../util/index.js'
 import { keyedProjects } from './keyed-projects.js'
 import { isDefaultBuild } from './projects.js'
-import { prepareSandbox } from './sandbox-request.js'
+import { commandWriteReach, prepareSandbox } from './sandbox-request.js'
 import type { OutputDirSnapshot, SaveFacts } from './miss-save.js'
 import { admitTasks, taintTracker } from './admission.js'
 import { unkeyedGroupOutcome, type ExecuteArgs } from './execute-task.js'
@@ -62,6 +61,7 @@ import { busLogger, createEventBus, terminalSubscriber, type EventBus } from './
 import { installPlugins, PluginSetupError } from './plugin.js'
 import { buildAdmission, executorLabel, resolveExecutors, teardownPlugins } from './plugin-host.js'
 import { subscribeTelemetry, type TelemetryHandle } from './telemetry-host.js'
+import { claimOutput, guardedOutput } from './output-host.js'
 import { assembleRunSummary, isPassStatus } from './telemetry.js'
 import type { RunContextRecord } from './telemetry.js'
 import { defaultLogger, type DefaultLogger, resolveOutputView, type Logger } from './logger.js'
@@ -121,10 +121,13 @@ import {
   type RunSummaryJson,
 } from './run-artifacts.js'
 import { createSaveLane } from './save-lane.js'
+import { commandWindows } from './command-windows.js'
 import { formatOutcomeTable, formatRunSummary } from './summary.js'
 import { detectFlaky, type FlakyCandidate, type FlakyFinding } from './failure-mode.js'
 import { createMissExplainer } from './miss-reason.js'
 import type { HeldServer, RunOptions, RunSummary } from './options.js'
+import { withRunSettings } from './run-settings.js'
+import { resolveSetting } from '../settings.js'
 
 // Per run, never shared: a `vx watch` process runs many, and a shared map
 // is one `preProbed.set` away from leaking a hit across cycles.
@@ -135,28 +138,6 @@ const emptyShortCircuit = (): ShortCircuit => ({
   groupKeys: new Map(),
 })
 
-/**
- * Parse the `VX_TASK_TIMEOUT` env var (ms) — the "global" run-level task
- * timeout default. A missing/empty/non-positive-integer value yields
- * `undefined` (ignored), so a typo never silently disables a task's own
- * `exec.timeout`. A value past `MAX_TIMEOUT_MS` is clamped to it — see below.
- *
- * Exported for `tests/options-resolve.test.ts`, which pins every accepted
- * and ignored form of this rung; it has no other caller outside this file.
- */
-export function readTaskTimeoutEnv(): number | undefined {
-  const raw = process.env['VX_TASK_TIMEOUT']
-  if (raw === undefined || raw === '') return undefined
-  const n = Number(raw)
-  if (!Number.isInteger(n) || n <= 0) return undefined
-  // CLAMPED, not refused — unlike `exec.timeout` and `--timeout`, this rung's
-  // contract is already "unusable value → fall back", so it never throws. But
-  // falling back is wrong here: someone who typed a huge number wants a long
-  // timeout, and the largest expressible one IS long (~24.8 days). Handing it
-  // to `setTimeout` unbounded would mean 1 ms — killing every task instantly.
-  return Math.min(n, MAX_TIMEOUT_MS)
-}
-
 /**
  * Compact the 4-axis cache policy into the `invocations.cache_policy`
  * column string. Each enabled axis contributes its flag; a fully-on
@@ -177,7 +158,7 @@ function compactCachePolicy(p: CachePolicy): string {
  * local cache writes NOWHERE, yet the write axis reads as on. Normalising
  * here — the ONE place both `run()` and `planRun()` derive it from — is
  * what keeps `--dry` describing the run you are about to get: reading the
- * raw request made the plan label `--cache=local:,remote:rw` "cache miss —
+ * raw request made the plan label `--cache-policy=local:,remote:rw` "cache miss —
  * would exec" (a result that will be stored) for a run in which caching is
  * entirely off.
  */
@@ -196,7 +177,7 @@ function effectiveCachePolicy(requested: CachePolicy, hasRemoteLayer: boolean):
  *     ingests hits into local for execute-task's lazy probe. The gate asks
  *     the layer (`hasRemote`), not `instanceof LayeredCache` — a
  *     third-party remote layer stalls on the classify just as hard.
- *   - the policy reads locally (a `--no-cache`/`--force`/`--cache=local:`
+ *   - the policy reads locally (a `--no-cache`/`--force`/`--cache-policy=local:`
  *     run reads nothing locally → nothing to restore → skip);
  *   - there is at least one task.
  * A flat graph has no ordering to bypass, but the classify pass is worth
@@ -289,6 +270,12 @@ function refuseRunOptions(options: RunOptions): void {
   oneOf('outputLogs', options.outputLogs, ['full', 'errors-only', 'none', 'hash-only'])
   oneOf('download', options.download, ['all', 'toplevel', 'none'])
   oneOf('flow', options.flow, ['focused', 'broad'])
+  oneOf('schedule', options.schedule, [
+    'most-work',
+    'critical-path',
+    'direct-dependents',
+    'ready-order',
+  ])
   const exclude = options.excludeDependencies
   if (exclude !== undefined && exclude !== 'all' && !names(exclude))
     refuse('excludeDependencies', exclude, "'all' or an array of task names")
@@ -299,11 +286,15 @@ function refuseRunOptions(options: RunOptions): void {
     refuse('concurrency', concurrency, 'a positive integer')
   if (retries !== undefined && !(Number.isInteger(retries) && retries >= 0))
     refuse('retries', retries, 'a non-negative integer')
-  if (
-    timeout !== undefined &&
-    !(Number.isInteger(timeout) && timeout > 0 && timeout <= MAX_TIMEOUT_MS)
-  )
-    refuse('timeout', timeout, `a positive integer of ms, at most ${MAX_TIMEOUT_MS}`)
+  for (const [name, ms] of [
+    ['timeout', timeout],
+    ['killGrace', options.killGrace],
+    ['teardownTimeout', options.teardownTimeout],
+    ['readyNotice', options.readyNotice],
+  ] as const) {
+    if (ms !== undefined && !(Number.isInteger(ms) && ms > 0 && ms <= MAX_TIMEOUT_MS))
+      refuse(name, ms, `a positive integer of ms, at most ${MAX_TIMEOUT_MS}`)
+  }
 }
 
 export async function run(options: RunOptions): Promise<RunSummary> {
@@ -332,6 +323,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
             coalesce: true,
             ...(options.tty === true ? { tty: true } : {}),
             ...(options.forwardArgs !== undefined ? { forwardArgs: options.forwardArgs } : {}),
+            ...(options.footer === false ? { footer: false } : {}),
           },
         )
       : null
@@ -344,16 +336,26 @@ export async function run(options: RunOptions): Promise<RunSummary> {
   // Tasks run with colour forced (exec/env.ts); where the terminal prints
   // plain, their escapes are stripped. A custom logger gets the task's
   // bytes as written, as the cache holds them: it formats its own output.
-  const unsubscribeTerminal = bus.subscribe(
-    terminalSubscriber(terminal === null || colors.enabled ? sink : plainOutput(sink)),
-  )
+  const render = terminalSubscriber(terminal === null || colors.enabled ? sink : plainOutput(sink))
+  let unsubscribeTerminal = bus.subscribe(render)
   const detach = (): void => {
     unsubscribeTerminal()
     terminal?.settle()
   }
+  // A plugin's `output` renders the run from its start; core's renderer
+  // stays the fallback. Only core's own renderer is replaceable: an
+  // embedder's `log` is never consulted away.
+  const takeOutput =
+    terminal === null
+      ? undefined
+      : (claimed: { logger: Logger; owner: string }): void => {
+          terminal.settle()
+          unsubscribeTerminal()
+          unsubscribeTerminal = bus.subscribe(guardedOutput(claimed, render))
+        }
   let held = false
   try {
-    const summary = await runOnBus(options, bus, colors, terminal)
+    const summary = await runOnBus(options, bus, colors, terminal, takeOutput)
     if (summary.persistent === undefined) return summary
     // Servers handed back still running still write: `vx watch dev` printed
     // none of its server's log while it idled, the renderer gone with this
@@ -377,6 +379,7 @@ async function runOnBus(
   bus: EventBus,
   colors: ColorSupport,
   terminal: DefaultLogger | null,
+  takeOutput?: (claimed: { logger: Logger; owner: string }) => void,
 ): Promise<RunSummary> {
   const log = busLogger(bus)
   // A server's output goes through a cell of its own: a later watch cycle
@@ -393,6 +396,7 @@ async function runOnBus(
   }
 
   const prepared = await prepareRun(options, log)
+  options = withRunSettings(options, prepared.workspaceConfig)
   mark('plugin stages')
   // Every exit from here tears the plugins down: their capability
   // factories ran in prepareRun, and teardown is what releases what those
@@ -494,14 +498,13 @@ async function runOnBus(
     cacheDir,
     cache,
     nodes,
-    workspaceFingerprint,
     fingerprintWatch,
     nestedDirsByProject,
     gitFilesCache,
     hashCache,
     workspaceProjectCount,
   } = prepared
-  const concurrency = options.concurrency ?? workspaceConfig?.concurrency ?? machineParallelism()
+  const concurrency = options.concurrency ?? machineParallelism()
   // An earlier cycle's servers: the ones this graph starts again unchanged
   // stay up; the others go now, before anything binds their ports. A stop
   // that lands meanwhile ends the run here, having run nothing: an aborted
@@ -593,7 +596,7 @@ async function runOnBus(
           }
         }
 
-  // `--download` (default `all`) decides ONCE per task, here, whether a
+  // `cache.download` (default `all`) decides ONCE per task, here, whether a
   // remote execution's outputs come home.
   const downloadPolicy = options.download ?? 'all'
   const localPlaced = locallyPlaced(placements, nodes.keys())
@@ -604,12 +607,19 @@ async function runOnBus(
     remoteOnly: placements.remoteOnly,
   })
 
-  // Run-level default task timeout (ms), applied to any task WITHOUT its own
-  // `exec.timeout`. Precedence, highest first: `--timeout`/RunOptions.timeout
-  // → `VX_TASK_TIMEOUT` env → workspace `timeout`. A malformed env value is
-  // ignored (a bad timeout must not silently disable a task's own limit).
-  const taskTimeoutDefault =
-    options.timeout ?? readTaskTimeoutEnv() ?? workspaceConfig?.timeout ?? undefined
+  // `run.timeout` (ms), for any task WITHOUT its own `exec.timeout`.
+  const taskTimeoutDefault = options.timeout
+  // Read once, before any task: a bad value is refused here, not mid-run.
+  const inputStability = {
+    run: inputStabilityEnv(),
+    ...(workspaceConfig?.cache?.inputStability !== undefined
+      ? { workspace: workspaceConfig.cache.inputStability }
+      : {}),
+  }
+
+  const cleanOutputs = resolveSetting('cache.outputs.clean', workspaceConfig).value as
+    | boolean
+    | undefined
 
   // Run-scoped registries of live subprocesses:
   //   - `liveChildren`: in-flight children. The runner adds/removes
@@ -698,7 +708,7 @@ async function runOnBus(
   // bumps are flushed, so a throw between opening the cache and the
   // normal close leaked the SQLite handle (it matters in a long-lived
   // host) AND lost this run's touch record, after which an LRU
-  // `vx cache prune` can evict entries the run just hit. Once-only
+  // `vx cache clean` can evict entries the run just hit. Once-only
   // because the normal path closes before the persistent-task wait —
   // holding the handle open for a dev server's whole lifetime would be
   // worse — and because close() re-runs its retention DELETEs.
@@ -739,7 +749,7 @@ async function runOnBus(
     const policy: CachePolicy = effectiveCachePolicy(prepared.cachePolicy, prepared.hasRemoteLayer)
     if (options.remoteRequested === true && !prepared.hasRemoteLayer) {
       log.status(
-        'vx: --cache named the remote cache, but no cache plugin in vx.workspace.* supplies one — the remote axes are off for this run',
+        'vx: --cache-policy named the remote cache, but no cache plugin in .vx/workspace.* supplies one — the remote axes are off for this run',
       )
     }
     const deferredOutputs = new DeferredOutputs({
@@ -756,7 +766,11 @@ async function runOnBus(
     // fails a run). `dirty` reuses the `git status --porcelain` the
     // GitFilesCache populate already ran for input enumeration — no
     // second status spawn.
-    const gitContext = captureGitContext(workspaceRoot, gitFilesCache.worktreeDirty)
+    // `run.branch` names the branch over git's (`prepared.branch`).
+    const gitContext = {
+      ...captureGitContext(workspaceRoot, gitFilesCache.worktreeDirty),
+      branch: prepared.branch(),
+    }
     const ciContext = detectCi(process.env)
     const hostContext = captureHostContext()
 
@@ -772,7 +786,7 @@ async function runOnBus(
     let runContextRecord: RunContextRecord | undefined
     // Gate on a plugin that can actually CONTRIBUTE a sink, not on declaring
     // any plugin at all: a cache-only plugin has no telemetry hook to
-    // consult, so paying for the record (2 git spawns + a `.vx/workspace-id`
+    // consult, so paying for the record (2 git spawns + a `.vx/cache/workspace-id`
     // write on a remote-less repo) buys nothing. A plugin that has the hook
     // but declines still pays — its answer is only knowable by asking.
     const hasTelemetryPlugin = prepared.plugins.some((p) => p.telemetry !== undefined)
@@ -857,6 +871,13 @@ async function runOnBus(
       log.status(`[vx] cache save failed: ${err instanceof Error ? err.message : String(err)}`),
     )
     const deferredSaves = new Map<string, Promise<SaveFacts>>()
+    const windows = commandWindows()
+    // A server held from an earlier run (`vx watch`) runs through this one
+    // too, so it may write a mutable input while it is described.
+    for (const id of heldBefore.kept.keys()) {
+      const node = nodes.get(id)!
+      windows.open(id, node.projectDir, commandWriteReach(node, workspaceRoot))
+    }
 
     // Focused flow: a requested GROUP has no output of its own, so
     // surface the same-project, non-group tasks it chains (one level)
@@ -895,6 +916,20 @@ async function runOnBus(
       workspaceProjectCount,
     }
 
+    // Asked only when a plugin declares `output`: a plain run pays nothing.
+    if (takeOutput !== undefined && prepared.plugins.some((p) => p.output !== undefined)) {
+      const json = options.json === true
+      const claimed = await claimOutput(prepared.plugins, {
+        workspaceRoot,
+        cacheDir,
+        warn: (m: string) => log.status(m),
+        isTTY: (json ? process.stderr : process.stdout).isTTY === true,
+        ci: ciContext.ci,
+        json,
+      })
+      if (claimed !== undefined) takeOutput(claimed)
+    }
+
     // Lifecycle hooks drive the default logger's dynamic status line
     // (TTY-only); custom loggers may ignore them.
     log.runStart?.({
@@ -909,7 +944,11 @@ async function runOnBus(
     terminal?.forecast(async () => {
       const ids: string[] = []
       for (const n of nodes.values()) if (!isGroupTask(n)) ids.push(n.id)
-      const p50s = await new LocalHistoryProvider(prepared.localCache.dbHandle()).p50sFor(ids)
+      const p50s = await new LocalHistoryProvider(
+        prepared.localCache.dbHandle(),
+        undefined,
+        prepared.branch(),
+      ).p50sFor(ids)
       return createForecast(nodes, p50s, concurrency)
     })
 
@@ -926,7 +965,7 @@ async function runOnBus(
         nodes,
         cache,
         workspaceRoot,
-        workspaceFingerprint,
+        claimedFiles: fingerprintWatch.names,
         forwardArgs: options.forwardArgs,
         nestedDirsByProject,
         gitFilesCache,
@@ -958,7 +997,7 @@ async function runOnBus(
         nodes,
         cache,
         workspaceRoot,
-        workspaceFingerprint,
+        claimedFiles: fingerprintWatch.names,
         forwardArgs: options.forwardArgs,
         nestedDirsByProject,
         gitFilesCache,
@@ -1031,7 +1070,6 @@ async function runOnBus(
         node,
         upstream,
         workspaceRoot,
-        workspaceFingerprint,
         cache,
         cachePolicy: policy,
         forwardArgs: options.forwardArgs,
@@ -1051,11 +1089,15 @@ async function runOnBus(
         outputDirSnapshots,
         deferSave: saveLane.defer,
         deferredSaves,
+        commandWindows: windows,
         stopSignal: stopRun.signal,
         failFast: failFast.signal,
       }
       if (options.retries !== undefined) a.retries = options.retries
       if (taskTimeoutDefault !== undefined) a.timeout = taskTimeoutDefault
+      if (options.readyNotice !== undefined) a.readyNotice = options.readyNotice
+      a.inputStability = inputStability
+      if (cleanOutputs !== undefined) a.cleanOutputs = cleanOutputs
       if (download.modeOf.get(node.id) === 'deferred') a.download = 'deferred'
       if (placements.remoteOnlyNoop.has(node.id)) a.remoteOnlyNoop = true
       if (placements.remoteOnly.has(node.id)) a.remoteOnly = true
@@ -1077,7 +1119,6 @@ async function runOnBus(
       shortCircuit,
       hashArgs: {
         workspaceRoot,
-        workspaceFingerprint,
         cache,
         forwardArgs: options.forwardArgs,
         nestedDirsByProject,
@@ -1135,6 +1176,7 @@ async function runOnBus(
         wallclockEndNs: at,
       }
     }
+    let lockBroken: boolean | undefined
     const outcomes = await runGraph({
       nodes,
       concurrency,
@@ -1156,7 +1198,15 @@ async function runOnBus(
         log.taskComplete(o.node, o)
         narrowDemand(o.node.id)
       },
-      onError: (node, line) => log.taskStderr(node, line),
+      // A crash a hand-broken lock entry caused is named as that; asked
+      // only here, so a run that does not crash pays nothing.
+      onError: (node, line, err) =>
+        log.taskStderr(
+          node,
+          !isUserError(err) && !isFsRefusal(err) && (lockBroken ??= lockEntryBroken(workspaceRoot))
+            ? `[vx] ${node.id}: ${LOCK_INVALID}\n`
+            : line,
+        ),
       execute: (node, upstream) => {
         const kept = keepServer(node)
         return kept !== undefined
@@ -1182,9 +1232,7 @@ async function runOnBus(
       // baseline as the tie-break. Empty map → baseline only.
       ...(priorities.size > 0 ? { priorities } : {}),
       // The baseline under them; `most-work` when the workspace names none.
-      ...(prepared.workspaceConfig?.schedule !== undefined
-        ? { strategy: prepared.workspaceConfig.schedule }
-        : {}),
+      ...(options.schedule !== undefined ? { strategy: options.schedule } : {}),
       // Local short-circuit: confirmed stable local hits the scheduler
       // runs ahead of their deps as low-priority worker-slot backfill.
       // Empty when the short-circuit didn't fire → byte-identical.
@@ -1276,7 +1324,7 @@ async function runOnBus(
     const stillDeferred = deferredOutputs.pending()
     if (stillDeferred.length > 0) {
       log.status(
-        `  Deferred: ${stillDeferred.length} task(s) left outputs remote (--download=none): ${stillDeferred.join(', ')}`,
+        `  Deferred: ${stillDeferred.length} task(s) left outputs remote (--cache-download=none): ${stillDeferred.join(', ')}`,
       )
     }
 
@@ -1506,7 +1554,8 @@ async function runOnBus(
     if (options.summaryTable === true) for (const line of formatOutcomeTable(list)) log.status(line)
     const above = options.beforeFooter?.(list, ok)
     if (above) log.status(above.replace(/\n$/, ''))
-    for (const line of formatRunSummary(list, totalMs, colors, runContext)) log.status(line)
+    if (options.footer !== false)
+      for (const line of formatRunSummary(list, totalMs, colors, runContext)) log.status(line)
 
     // Edge case the summary already reported: the user requested a
     // persistent task (dev server / watcher). The run is "done" in every
@@ -1652,18 +1701,16 @@ async function runOnBus(
 }
 
 /**
- * The workspace's `cacheRetention`, after every save and upload of this run
+ * `cache.retention`, after every save and upload of this run
  * has landed (so nothing this run wrote is mid-flight) and before the cache
  * closes. Housekeeping, not the run's work: silent, and a failure is never
  * a failed run. Declared nowhere → one property read.
  */
 async function applyCacheRetention(prepared: PreparedRun): Promise<void> {
-  const retention = prepared.workspaceConfig?.cacheRetention
-  if (retention === undefined) return
-  // Validated at load (`validateRetention`), so both parse.
-  const maxAgeMs =
-    retention.olderThan === undefined ? undefined : parseDuration(retention.olderThan)!
-  const maxBytes = retention.maxSize === undefined ? undefined : parseSize(retention.maxSize)!
+  const ws = prepared.workspaceConfig
+  const maxAgeMs = resolveSetting('cache.retention.olderThan', ws).value as number | undefined
+  const maxBytes = resolveSetting('cache.retention.maxSize', ws).value as number | undefined
+  if (maxAgeMs === undefined && maxBytes === undefined) return
   try {
     await prepared.localCache.evictIfDue({
       ...(maxAgeMs !== undefined ? { maxAgeMs } : {}),
@@ -1708,6 +1755,7 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
   const log = options.log ?? defaultLogger(undefined, undefined, process.stderr)
   const reasons = new Map<string, AffectedReason>()
   const prepared = await prepareRun({ ...options, affectedReasons: reasons }, log)
+  options = withRunSettings(options, prepared.workspaceConfig)
   try {
     if (prepared.unresolvedTasks.length > 0) {
       return {
@@ -1735,7 +1783,6 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
     const planned = await plan({
       nodes: prepared.nodes,
       workspaceRoot: prepared.workspaceRoot,
-      workspaceFingerprint: prepared.workspaceFingerprint,
       cache: prepared.cache,
       cachePolicy: policy,
       forwardArgs: options.forwardArgs,
@@ -1747,7 +1794,11 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
       // per-task p50s + a predicted wall-clock. `--dry` is an explicit
       // inspection command, so the history read's cost is fine here even
       // though it stays OFF the default run path.
-      history: new LocalHistoryProvider(prepared.localCache.dbHandle()),
+      history: new LocalHistoryProvider(
+        prepared.localCache.dbHandle(),
+        undefined,
+        prepared.branch(),
+      ),
       // Placement, by the same rules the run applies. Only worth showing
       // when there is a choice to show — with one declared executor every
       // line would carry the same label. Resolving the executors here is
@@ -1797,7 +1848,7 @@ async function planRestorable(
     nodes,
     cache: prepared.cache,
     workspaceRoot: prepared.workspaceRoot,
-    workspaceFingerprint: prepared.workspaceFingerprint,
+    claimedFiles: prepared.fingerprintWatch.names,
     forwardArgs,
     nestedDirsByProject: prepared.nestedDirsByProject,
     gitFilesCache: prepared.gitFilesCache,
@@ -1815,25 +1866,13 @@ function elsewhereHint(names: readonly string[]): string {
 }
 
 /**
- * The first-run case, told apart from a typo: no package in the workspace
+ * The first-run case, told apart from a typo: no project in the workspace
  * has a `vx.config.*` at all, so no name could have resolved. Reached only
- * on the error path. A workspace whose package globs match NOTHING is
- * told that instead — `vx init` would find no package to write for.
+ * on the error path.
  */
-async function initHint(prepared: {
-  anyProjectConfig: boolean
-  workspaceProjectCount: number
-  workspaceRoot: string
-}): Promise<string> {
+async function initHint(prepared: { anyProjectConfig: boolean }): Promise<string> {
   if (prepared.anyProjectConfig) return ''
-  if (prepared.workspaceProjectCount === 0) {
-    return " No package matched the workspace's package globs — check `workspaces` in package.json (or pnpm-workspace.yaml)."
-  }
-  // Single-project mode with packages the root's missing `workspaces`
-  // never reaches: `vx init` would find no scripts either (item 248).
-  const unreached = await unreachedPackages(await loadWorkspace(prepared.workspaceRoot))
-  if (unreached.length > 0) return ` ${unreachedHint(unreached, prepared.workspaceRoot)}`
-  return ' No package declares a vx.config — run `vx init` to write one per package from its package.json scripts.'
+  return ' No directory holds a vx.config — run `vx init` to write them, then `vx lock`.'
 }
 
 /**
@@ -1879,7 +1918,7 @@ function didYouMean(
     // `//` is two edits from any two-letter name: it hinted `ui#build` (X-13).
     if (proj === '//') {
       lists.add(
-        "`//` is Turbo's root package, but the workspace root is no project here: give it a package.json name and a vx.config with that task.",
+        '`//` is the workspace root, which is no project here: add a vx.config there with that task and run `vx lock`.',
       )
       continue
     }

package/src/orchestrator/sandbox-fix.ts

@@ -1,5 +1,5 @@
 // The `exec.sandbox.allow` entries that would have granted what a failed
-// task was denied, so the report names the line to add (CLI, JSON, MCP)
+// task was denied, so the report names the line to add (CLI, JSON)
 // rather than leaving the user to turn absolute paths into grants. Built on
 // the failure path only: a passing run never calls it.
 
@@ -9,26 +9,22 @@ import path from 'node:path'
 import type { SandboxViolation } from '../exec/index.js'
 import type { TaskOutcome } from '../graph/index.js'
 import { isLiteralPattern } from '../util/index.js'
+import { CREDENTIAL_STORES } from './sandbox-request.js'
 
 /** Grants to add under `exec.sandbox.allow`, each list sorted and unique. */
 type SandboxFix = NonNullable<TaskOutcome['sandboxFix']>
-type Kind = Exclude<keyof SandboxFix, 'withheld'>
-
-// Where credentials live. A denial here is never turned into a grant: an
-// agent applies `sandboxFix` as given, so a dependency probing ~/.ssh would
-// get its grant suggested and applied (Security, 2026-10-12).
-const CREDENTIAL_DIRS = ['.ssh', '.aws', '.gnupg', '.kube', '.config/gh', '.config/gcloud']
-const CREDENTIAL_FILES = ['.netrc', '.npmrc', '.docker/config.json', '.git-credentials', '.pypirc']
+type Kind = Exclude<keyof SandboxFix, 'withheld' | 'inputs'>
 
+// A denial in a credential store is never turned into a grant: an agent
+// applies `sandboxFix` as given, so a dependency probing ~/.ssh would get
+// its grant suggested and applied (Security, 2026-10-12). The stores are
+// the ones the sandbox denies: a hand copy here missed half of them.
 function isCredential(abs: string): boolean {
   const base = path.basename(abs)
   if (base === '.env' || base.startsWith('.env.')) return true
   const rel = path.relative(os.homedir(), abs)
   if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return false
-  return (
-    CREDENTIAL_FILES.includes(rel) ||
-    CREDENTIAL_DIRS.some((d) => rel === d || rel.startsWith(d + path.sep))
-  )
+  return CREDENTIAL_STORES.some((d) => rel === d || rel.startsWith(d + path.sep))
 }
 
 /**
@@ -63,6 +59,16 @@ function readsDir(g: string, top: string): boolean {
   return first === top || !isLiteralPattern(first)
 }
 
+const inProject = (grant: string): boolean => !grant.startsWith('~/') && !path.isAbsolute(grant)
+
+/** Whether a project-relative path is one the task's input globs match. */
+function keyedBy(globs: readonly string[]): (rel: string) => boolean {
+  const strip = (g: string) => g.replace(/^\.\//, '')
+  const take = globs.filter((g) => !g.startsWith('!')).map((g) => new Bun.Glob(strip(g)))
+  const drop = globs.filter((g) => g.startsWith('!')).map((g) => new Bun.Glob(strip(g.slice(1))))
+  return (rel) => take.some((g) => g.match(rel)) && !drop.some((g) => g.match(rel))
+}
+
 function kindOf(v: SandboxViolation): Kind | undefined {
   const can = v.ignorable ?? []
   if (can.length === 1) return can[0]
@@ -78,16 +84,22 @@ export function sandboxFix(
   violations: readonly SandboxViolation[],
   projectDir: string,
   mask: (text: string) => string = (t) => t,
-  /** The task's `cache.inputs.files`: a write under one is granted exactly. */
-  inputs: readonly string[] = [],
+  /**
+   * The task's `cache.inputs.files`, undefined when it does not cache: a
+   * write under one is granted exactly, and a read of the project no glob
+   * matches is named for the key too.
+   */
+  inputs?: readonly string[],
 ): SandboxFix | undefined {
-  const fix: Record<Kind | 'withheld', Set<string>> = {
+  const fix: Record<Kind | 'withheld' | 'inputs', Set<string>> = {
     read: new Set(),
     write: new Set(),
     network: new Set(),
     systemInfo: new Set(),
     withheld: new Set(),
+    inputs: new Set(),
   }
+  const keyed = inputs === undefined ? undefined : keyedBy(inputs)
   for (const v of violations) {
     if (v.hint === true || v.target === undefined) continue
     const kind = kindOf(v)
@@ -96,16 +108,19 @@ export function sandboxFix(
     else if (kind === 'systemInfo') fix.systemInfo.add(v.target)
     else if (v.path === undefined) continue
     else if (isCredential(v.path)) fix.withheld.add(grantPath(v.path, projectDir))
-    else if (kind === 'read') fix.read.add(grantPath(v.path, projectDir))
-    else {
+    else if (kind === 'read') {
+      const grant = grantPath(v.path, projectDir)
+      fix.read.add(grant)
+      if (keyed !== undefined && inProject(grant) && !keyed(grant)) fix.inputs.add(grant)
+    } else {
       const isDir =
         v.line.startsWith('mkdir') ||
         lstatSync(v.path, { throwIfNoEntry: false })?.isDirectory() === true
-      fix.write.add(writeGrant(grantPath(v.path, projectDir), isDir, inputs))
+      fix.write.add(writeGrant(grantPath(v.path, projectDir), isDir, inputs ?? []))
     }
   }
   const out: SandboxFix = {}
-  for (const k of ['read', 'write', 'network', 'systemInfo', 'withheld'] as const)
+  for (const k of ['read', 'write', 'network', 'systemInfo', 'withheld', 'inputs'] as const)
     if (fix[k].size > 0) out[k] = [...new Set([...fix[k]].map(mask))].sort()
   return Object.keys(out).length > 0 ? out : undefined
 }
@@ -114,7 +129,11 @@ export function sandboxFix(
  * The fix as the config line it is: `exec.sandbox.allow: { read: ['a'] }`,
  * or undefined when every denial was a withheld credential path.
  */
-export function sandboxFixLine({ withheld: _, ...fix }: SandboxFix): string | undefined {
+export function sandboxFixLine({
+  withheld: _,
+  inputs: __,
+  ...fix
+}: SandboxFix): string | undefined {
   if (Object.keys(fix).length === 0) return undefined
   const parts = Object.entries(fix).map(
     ([k, list]: [string, string[]]) => `${k}: [${list.map((p) => `'${p}'`).join(', ')}]`,