@vzn/vx 0.0.636 → 0.0.638

package/src/orchestrator/run.ts

@@ -3,12 +3,7 @@
 // so the layers can be swapped without touching the others.
 
 import type { ProjectEntry } from '../workspace/index.js'
-import {
-  inputStabilityEnv,
-  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 {
@@ -16,6 +11,11 @@ import {
   type CacheLayer,
   type CachePolicy,
   cachesNothing,
+  formatCachePolicy,
+  packRunOutputs,
+  resolveOutputs,
+  resolveWorkspaceOutputs,
+  runEntryName,
   stopRuntimeProbes,
 } from '../cache/index.js'
 import { VERSION } from '../version.js'
@@ -42,8 +42,6 @@ import {
   stageTimes,
   killGraceMs,
   MAX_TIMEOUT_MS,
-  parseDuration,
-  parseSize,
   printTimings,
   ulid,
   isLiteralPattern,
@@ -54,23 +52,28 @@ import {
   teardownTimeoutMs,
   secretMask,
   isFsRefusal,
+  isUserError,
+  detectColors,
+  relPosix,
+  type ColorSupport,
 } 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'
 import { excludedTaint } from './excluded-keys.js'
 import { keyUpstream } from './upstream.js'
 import { busLogger, createEventBus, terminalSubscriber, type EventBus } from './events.js'
-import { installPlugins, PluginSetupError } from './plugin.js'
+import { installPlugins, PluginSetupError, type RunReport, type RunReportTask } from './plugin.js'
+import { decodeOutputLog } from './output-log.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'
-import { detectColors, type ColorSupport } from './colors.js'
 import { plainOutput } from './plain-output.js'
 import { formatPersistentList } from './framed-output.js'
 import { createForecast } from './forecast.js'
@@ -126,10 +129,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.
@@ -140,40 +146,19 @@ 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
- * policy reads `'lR,lW,rR,rW'`. Pure presentation — never affects the key.
- */
-function compactCachePolicy(p: CachePolicy): string {
-  const parts: string[] = []
-  if (p.localRead) parts.push('lR')
-  if (p.localWrite) parts.push('lW')
-  if (p.remoteRead) parts.push('rR')
-  if (p.remoteWrite) parts.push('rW')
-  return parts.join(',')
+/** The files `node`'s declared outputs match on disk now, workspace-relative and sorted. */
+async function outputsLeft(
+  node: TaskNode,
+  workspaceRoot: string,
+  nestedProjectDirs: string[],
+): Promise<string[]> {
+  const declared = node.config.cache?.outputs
+  if (declared === undefined) return []
+  const [own, ws] = await Promise.all([
+    resolveOutputs({ projectDir: node.projectDir, outputs: declared.files, nestedProjectDirs }),
+    resolveWorkspaceOutputs({ workspaceRoot, outputs: declared.workspaceFiles ?? [] }),
+  ])
+  return [...new Set([...own, ...ws].map((p) => relPosix(workspaceRoot, p)))].sort()
 }
 
 /**
@@ -182,7 +167,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.
  */
@@ -201,7 +186,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
@@ -294,6 +279,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")
@@ -304,11 +295,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> {
@@ -337,6 +332,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
@@ -349,16 +345,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
@@ -382,6 +388,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
@@ -398,6 +405,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
@@ -406,11 +414,11 @@ async function runOnBus(
   // per cycle under `vx watch`. A plugin whose own setup threw set up
   // nothing, and is the one left out.
   let tornDown = false
-  const teardown = async (except?: unknown): Promise<void> => {
+  const teardown = async (except?: unknown, report?: RunReport): Promise<void> => {
     if (tornDown) return
     tornDown = true
     const plugins = prepared.plugins.filter((p) => p !== except)
-    await teardownPlugins(plugins, (m) => log.status(m))
+    await teardownPlugins(plugins, (m) => log.status(m), report)
   }
   // A task whose command re-enters `vx run` in the workspace running it
   // is refused. When the inner run reaches this task again it forks a run
@@ -438,7 +446,7 @@ async function runOnBus(
   // A refusal is the caller's to print (on stderr, as `vx run:`): as a
   // status line it went to stdout, into whatever a script piped there.
   if (prepared.unresolvedTasks.length > 0) {
-    const refused = `no projects declare task(s): ${prepared.unresolvedTasks.join(', ')}.${elsewhereHint(prepared.declaredElsewhere)}${didYouMean(prepared.unresolvedTasks, prepared.hintProjects, prepared.declaredElsewhere)}${await initHint(prepared)}`
+    const refused = `no projects declare task(s): ${prepared.unresolvedTasks.join(', ')}.${await unresolvedHint(prepared)}`
     await teardown()
     prepared.cache.close()
     return { ok: false, outcomes: [], refused }
@@ -468,6 +476,13 @@ async function runOnBus(
   // the plugin. A plugin without `setup` subscribes nothing.
   let disposePlugins: (() => void) | undefined
   let telemetry: TelemetryHandle | undefined
+  // One run-id per `vx run` invocation. Every task in the resulting graph
+  // carries it so analytics queries can group by invocation; plugins get it
+  // in their teardown's `RunReport`.
+  const runId = ulid()
+  const head = captureGitContext(prepared.workspaceRoot)
+  const ciContext = detectCi(process.env)
+  const keepRunLog = prepared.keepRunEntry !== undefined
   try {
     disposePlugins = await installPlugins({
       plugins: prepared.plugins,
@@ -475,6 +490,9 @@ async function runOnBus(
       workspaceRoot: prepared.workspaceRoot,
       cacheDir: prepared.cacheDir,
       warn: (m) => log.status(m),
+      cache: prepared.cacheFor,
+      ci: ciContext.ci,
+      branch: prepared.branch(),
     })
   } catch (err) {
     disposePlugins?.()
@@ -499,14 +517,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
@@ -598,7 +615,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())
@@ -609,20 +626,20 @@ 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?.inputStability !== undefined
-      ? { workspace: workspaceConfig.inputStability }
+    ...(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
   //     each child around its spawn (persistent children stay until
@@ -710,7 +727,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.
@@ -737,9 +754,6 @@ async function runOnBus(
     }),
   )
   try {
-    // One run-id per `vx run` invocation. Every task in the resulting
-    // graph carries it so analytics queries can group by invocation.
-    const runId = ulid()
     const runStartHrTimeNs = process.hrtime.bigint()
     const endedAtMsAtStart = Date.now()
     const remoteCacheEnabled = prepared.hasRemoteLayer
@@ -751,7 +765,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({
@@ -768,8 +782,12 @@ 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)
-    const ciContext = detectCi(process.env)
+    // `run.branch` names the branch over git's (`prepared.branch`).
+    const gitContext = {
+      ...head,
+      dirty: gitFilesCache.worktreeDirty,
+      branch: prepared.branch(),
+    }
     const hostContext = captureHostContext()
 
     // The canonical run-context record — the same git/CI/host data the
@@ -784,7 +802,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)
@@ -807,7 +825,7 @@ async function runOnBus(
           invocationCommand(options.command?.split(' ') ?? process.argv.slice(1)),
         ),
         requestedTasks: [...options.tasks],
-        cachePolicy: compactCachePolicy(policy),
+        cachePolicy: formatCachePolicy(policy),
         concurrency,
         flow: options.flow ?? null,
         commitSha: gitContext.commitSha,
@@ -869,6 +887,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)
@@ -903,10 +928,31 @@ async function runOnBus(
       version: VERSION,
       packageCount: packagesInScope.size,
       remoteCacheEnabled,
+      cache: {
+        local: policy.localRead || policy.localWrite,
+        localWrite: policy.localWrite,
+        remote: remoteCacheEnabled && (policy.remoteRead || policy.remoteWrite),
+        uploads: prepared.localCache.uploads,
+        notDownloaded: () => deferredOutputs.pending().length,
+      },
       concurrency,
       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?.({
@@ -921,7 +967,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)
     })
 
@@ -938,7 +988,7 @@ async function runOnBus(
         nodes,
         cache,
         workspaceRoot,
-        workspaceFingerprint,
+        claimedFiles: fingerprintWatch.names,
         forwardArgs: options.forwardArgs,
         nestedDirsByProject,
         gitFilesCache,
@@ -970,7 +1020,7 @@ async function runOnBus(
         nodes,
         cache,
         workspaceRoot,
-        workspaceFingerprint,
+        claimedFiles: fingerprintWatch.names,
         forwardArgs: options.forwardArgs,
         nestedDirsByProject,
         gitFilesCache,
@@ -1043,7 +1093,6 @@ async function runOnBus(
         node,
         upstream,
         workspaceRoot,
-        workspaceFingerprint,
         cache,
         cachePolicy: policy,
         forwardArgs: options.forwardArgs,
@@ -1063,12 +1112,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
@@ -1078,6 +1130,7 @@ async function runOnBus(
       if (upfrontKey !== undefined) a.upfrontKey = upfrontKey
       if (upfrontGroupKey !== undefined) a.upfrontGroupKey = upfrontGroupKey
       if (tainted) a.taintedUpstream = true
+      if (keepRunLog) a.keepRunLog = true
       if (!dependedOn.has(node.id)) a.noDependants = true
       if (holders.has(node.id)) a.terminal = true
       if (armSandbox !== undefined) a.armSandbox = armSandbox
@@ -1090,7 +1143,6 @@ async function runOnBus(
       shortCircuit,
       hashArgs: {
         workspaceRoot,
-        workspaceFingerprint,
         cache,
         forwardArgs: options.forwardArgs,
         nestedDirsByProject,
@@ -1148,6 +1200,7 @@ async function runOnBus(
         wallclockEndNs: at,
       }
     }
+    let lockBroken: boolean | undefined
     const outcomes = await runGraph({
       nodes,
       concurrency,
@@ -1169,7 +1222,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
@@ -1195,9 +1256,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.
@@ -1289,7 +1348,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: left outputs remote (--cache-download=none): ${stillDeferred.join(', ')}`,
       )
     }
 
@@ -1297,6 +1356,55 @@ async function runOnBus(
     // change the run's exit code — the run already happened.
     // Written again after the keep-alive wait: a kept server's crash or a
     // Ctrl-C there is the process's exit, and the first write said ok.
+    // The run's own bytes, kept in a remote that takes its writes (owner
+    // 2026-10-15): a failed task's log and the files its outputs left, an
+    // uncached task's log. Then the report every plugin's teardown reads.
+    const keepRunBytes = async (final: readonly TaskOutcome[]): Promise<RunReport> => {
+      const keep = prepared.keepRunEntry
+      const tasks: RunReportTask[] = []
+      const work: (() => Promise<void>)[] = []
+      for (const o of final) {
+        if (isGroupTask(o.node)) continue
+        const task: { -readonly [K in keyof RunReportTask]: RunReportTask[K] } = {
+          id: o.node.id,
+          status: o.status,
+          durationMs: Math.round(o.durationMs),
+          ...(o.hash !== undefined ? { key: o.hash } : {}),
+        }
+        tasks.push(task)
+        if (keep === undefined) continue
+        const runLog = o.runLog
+        if (runLog !== undefined) {
+          work.push(async () => {
+            const text = decodeOutputLog(runLog)
+              .map((c) => c.text)
+              .join('')
+            if (text.length === 0) return
+            const name = runEntryName(runId, o.node.id, 'log')
+            if (await keep(name, new TextEncoder().encode(text))) task.log = name
+          })
+        }
+        if (o.status === 'failed' && o.where === undefined) {
+          work.push(async () => {
+            const bytes = await packRunOutputs(
+              prepared.workspaceRoot,
+              await outputsLeft(
+                o.node,
+                prepared.workspaceRoot,
+                prepared.nestedDirsByProject.get(o.node.projectName) ?? [],
+              ),
+            )
+            if (bytes === null) return
+            const name = runEntryName(runId, o.node.id, 'outputs')
+            if (await keep(name, bytes)) task.outputs = name
+          })
+        }
+      }
+      for (let i = 0; i < work.length; i += 8) {
+        await Promise.all(work.slice(i, i + 8).map((w) => w()))
+      }
+      return { runId, commit: head.commitSha, ciRun: ciContext, ok, tasks }
+    }
     let json: RunSummaryJson | undefined
     const summarize = async (runOk: boolean, final = list): Promise<void> => {
       if (options.json === true) {
@@ -1370,7 +1478,7 @@ async function runOnBus(
         // own output masks it, so cache.db holds no plaintext value.
         command: maskInvocation(options.command ?? process.argv.slice(1).join(' ')),
         requestedTasks: options.tasks,
-        cachePolicy: compactCachePolicy(policy),
+        cachePolicy: formatCachePolicy(policy),
         concurrency,
         flow: options.flow ?? null,
         forwardArgs: options.forwardArgs,
@@ -1435,6 +1543,7 @@ async function runOnBus(
     // drain of the lane stood here until item 634; deleting it changed
     // nothing the suite could see, because this gate is the rule.
     await cache.drainUploads?.()
+    const report = await keepRunBytes(list)
     // Hand the per-run summary to the telemetry sinks + drain them. Only
     // when a sink is active (telemetry !== undefined) — otherwise this
     // whole block is skipped and the run is byte-identical to before.
@@ -1493,7 +1602,7 @@ async function runOnBus(
     // whole keep-alive wait below (C-66). Idempotent; the finally's stay.
     disposePlugins?.()
     telemetry?.dispose()
-    await teardown()
+    await teardown(undefined, report)
     await closeCache()
     mark('close')
     printTimings()
@@ -1519,7 +1628,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
@@ -1665,18 +1775,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 } : {}),
@@ -1721,12 +1829,13 @@ 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 {
         tasks: [],
         unresolvedTasks: prepared.unresolvedTasks,
-        unresolvedHint: `${elsewhereHint(prepared.declaredElsewhere)}${didYouMean(prepared.unresolvedTasks, prepared.hintProjects, prepared.declaredElsewhere)}${await initHint(prepared)}`,
+        unresolvedHint: await unresolvedHint(prepared),
       }
     }
     if (prepared.empty === 'no-tasks-declared' && prepared.declaredElsewhere.length > 0) {
@@ -1748,7 +1857,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,
@@ -1760,7 +1868,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
@@ -1810,7 +1922,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,
@@ -1828,25 +1940,38 @@ function elsewhereHint(names: readonly string[]): string {
 }
 
 /**
- * The first-run case, told apart from a typo: no package 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.
+ * What follows "no projects declare task(s): …": where the name is, its
+ * nearest spelling, and, with neither, the lock a run reads its configs
+ * from: a task just added to a vx.config is not in it until `vx lock`.
  */
-async function initHint(prepared: {
+async function unresolvedHint(prepared: {
+  unresolvedTasks: readonly string[]
+  hintProjects: ReadonlyMap<string, ProjectEntry>
+  declaredElsewhere: readonly string[]
   anyProjectConfig: boolean
-  workspaceProjectCount: number
-  workspaceRoot: string
 }): Promise<string> {
+  const elsewhere = elsewhereHint(prepared.declaredElsewhere)
+  const near = didYouMean(
+    prepared.unresolvedTasks,
+    prepared.hintProjects,
+    prepared.declaredElsewhere,
+  )
+  const init = await initHint(prepared)
+  const lock =
+    init === '' && elsewhere === '' && !near.startsWith(' Did you mean')
+      ? ' A run reads the lock: after editing a vx.config, run `vx lock`.'
+      : ''
+  return `${elsewhere}${near}${init}${lock}`
+}
+
+/**
+ * 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.
+ */
+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`.'
 }
 
 /**
@@ -1892,7 +2017,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
     }