@vzn/vx 0.0.636 → 0.0.638

package/src/orchestrator/projects.ts

@@ -4,30 +4,30 @@
 // plugin `project` stage, which can give tasks to a package that never
 // wrote a `vx.config.ts`.
 
+import { stat } from 'node:fs/promises'
 import path from 'node:path'
 import type { ProjectConfig, TaskConfig } from '../config.js'
 import {
+  checkProjectNames,
   frozenProjectConfigs,
-  loadProjectConfigs,
   LOCKFILE_NAME,
+  lockedProjects,
+  NO_LOCK,
+  pathName,
+  readLockfile,
   validateProjectConfig,
-  type LoadProjectConfigOptions,
-  type LoadReads,
   type Lockfile,
   type PackageGraph,
   type ProjectEntry,
   type ProjectMeta,
-  type Workspace,
 } from '../workspace/index.js'
 import type { WorkspaceConfig } from '../config.js'
-import { Cache, lazyGitEnumeration, type LazyGitEnumeration } from '../cache/index.js'
-import { UserError } from '../util/index.js'
+import { lazyGitEnumeration, type LazyGitEnumeration } from '../cache/index.js'
+import { relPosix, UserError } from '../util/index.js'
 import {
-  computeWorkspaceFingerprint,
-  listProjects,
-  loadWorkspace,
   loadWorkspaceConfig,
-  namedProject,
+  discoveredProject,
+  linkDiscoveredEdges,
   resolveCacheDir,
   validateWorkspace,
 } from '../workspace/index.js'
@@ -61,7 +61,7 @@ export async function loadWorkspacePlugins(
   // the loader would refuse from a user (`concurrency: -3`) hung the run,
   // and `cacheDir: 42` reached `path.resolve` as a TypeError.
   await applyConfigHooks(plugins, workspaceConfig, { workspaceRoot, warn }, (plugin) =>
-    validateWorkspace(workspaceConfig, `vx.workspace (after plugin '${plugin.name}')`),
+    validateWorkspace(workspaceConfig, `.vx/workspace (after plugin '${plugin.name}')`),
   )
   return { workspaceConfig, plugins }
 }
@@ -77,6 +77,15 @@ export function gitOfDiscovery(projects: readonly ProjectMeta[]): LazyGitEnumera
   return discoveredGit.get(projects)
 }
 
+/** The lock a discovery read, by the array it returned: a later config load reads no second copy. */
+const discoveredLock = new WeakMap<readonly ProjectMeta[], () => Promise<Lockfile>>()
+
+export function lockOfDiscovery(
+  projects: readonly ProjectMeta[],
+): (() => Promise<Lockfile>) | undefined {
+  return discoveredLock.get(projects)
+}
+
 /**
  * The package graph a selection pass built over a discovery, by that
  * discovery's array, when it folded no task edge in: the graph a run that
@@ -93,34 +102,40 @@ export function keepDiscoveryGraph(projects: readonly ProjectMeta[], graph: Pack
 }
 
 /**
- * The workspace's projects: core's discovery, then the plugin `discover`
- * stage. With no plugin declaring it, `listProjects` alone.
+ * The workspace's projects: the directories the lock records (a run never
+ * walks for configs), then the plugin `discover` stage, which may add
+ * directories, name path-named ones and give edges. Sorted by name; two
+ * projects of one name are refused.
  */
 export async function discoverProjects(
-  workspace: Workspace,
+  workspaceRoot: string,
+  lock: () => Promise<Lockfile>,
   plugins: readonly VxPlugin[],
   cacheDir: string,
   warn: (message: string) => void,
   /** The run's enumeration, which `DiscoverContext.worktreeChanges` reads (and starts). */
-  git: LazyGitEnumeration = lazyGitEnumeration(workspace.root),
+  git: LazyGitEnumeration = lazyGitEnumeration(workspaceRoot),
 ): Promise<ProjectMeta[]> {
-  const projects = await listProjects(workspace)
+  const projects = lockedProjects(workspaceRoot, (await lock()).projects)
   // Registered whatever the hooks: an `--affected` selection reads its
   // untracked files from this walk, and the run reuses it (I-26).
   discoveredGit.set(projects, git)
-  if (!hasHook(plugins, 'discover')) return projects
+  discoveredLock.set(projects, lock)
+  if (!hasHook(plugins, 'discover')) return checkProjectNames(workspaceRoot, projects)
   const worktreeChanges = (): Promise<readonly string[] | null> =>
     git.start().then(
       (e) => e.changed,
       () => null,
     )
-  await applyDiscoverHooks(
+  const edges = await applyDiscoverHooks(
     plugins,
     projects,
-    { workspaceRoot: workspace.root, cacheDir, warn, worktreeChanges },
-    (named, plugin) => namedProject(workspace, projects, named, plugin.name),
+    { workspaceRoot, cacheDir, warn, worktreeChanges },
+    (entry, plugin) => discoveredProject(workspaceRoot, projects, entry, plugin.name),
   )
-  return projects.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+  checkProjectNames(workspaceRoot, projects)
+  linkDiscoveredEdges(workspaceRoot, projects, edges)
+  return projects
 }
 
 export type LoadProjectsArgs = LoadProjectsBase &
@@ -142,13 +157,14 @@ interface LoadProjectsBase {
    */
   seeds: 'all' | Iterable<string>
   /**
-   * Read configs from the lock instead of evaluating them (`--frozen`),
-   * asked only when a config is to be read: a run whose every config the
-   * CLI's selection pass staged never parses it again.
+   * The lock configs come from, asked only when a config is to be read (a
+   * run whose every config the CLI's selection pass staged never parses
+   * it). `vx lock` hands the one it is about to write.
    */
-  lock: (() => Promise<Lockfile>) | null
-  evalCache: LoadProjectConfigOptions['evalCache']
+  configs: () => Promise<Lockfile>
   warn: (message: string) => void
+  /** `vx lock`'s audit: the `project` stage's `ctx.lock`. */
+  lock?: boolean
   /**
    * Entries a load in this same process already produced with the same
    * cache dir and lock (the CLI's selection pass, which stages every
@@ -180,7 +196,8 @@ export interface LoadedProjects {
  * enters scope.
  */
 export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjects> {
-  const { plugins, lock, workspaceRoot } = args
+  const { plugins, workspaceRoot } = args
+  const lock = args.configs
   const graph = args.closure ? args.packageGraph : null
   // A package with no config file declares no tasks — unless a plugin
   // fills the `project` stage, in which case it is a project the stage may
@@ -238,27 +255,13 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
   // deps by design), so its config has to be pulled in — and that config
   // may declare cross edges of its own. The common case (no cross deps)
   // is a single round, identical to loading the closure in one batch.
-  // Turbo spells the root package `//` (`dependsOn: ['//#lint']`); vx names
-  // the root project by its package.json name, so the spelling is rewritten
-  // to it once, here, for the closure, the graph and `cache.inputs.tasks`
-  // alike. With no root project it stays, and the graph's refusal says so.
+  // Turbo spells the root package `//` (`dependsOn: ['//#lint']`), as vx
+  // names the root project unless something names it; a named root's
+  // spelling is rewritten to its name once, here, for the closure, the
+  // graph and `cache.inputs.tasks` alike. With no root project it stays,
+  // and the graph's refusal says so.
   const root = path.resolve(workspaceRoot)
   const rootName = args.projectMetas.find((m) => path.resolve(m.dir) === root)?.name
-  // A project the lock holds whose config file is gone ran nothing under
-  // --frozen, green, though the lock promises what runs is what was
-  // locked (X-144); a run never even asks such a project for a task.
-  // Refused as a moved config is (D-88). With no lock at all, nothing was
-  // locked: a repo of config-less projects needs none.
-  if (lock) {
-    const bare = args.projectMetas.filter((m) => m.configPath === null)
-    const held = bare.length === 0 ? null : await lock().catch(() => null)
-    const gone = held === null ? undefined : bare.find((m) => Object.hasOwn(held.projects, m.name))
-    if (gone !== undefined && held !== null)
-      throw new UserError(
-        `${LOCKFILE_NAME} locks "${gone.name}" at ${held.projects[gone.name]!.configPath}, but it has no config now — ` +
-          `run \`vx lock\` to refresh, or delete ${LOCKFILE_NAME}`,
-      )
-  }
   const projects = new Map<string, ProjectEntry>()
   while (pending.length > 0) {
     const round = pending.splice(0, pending.length)
@@ -269,14 +272,30 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
       (m): m is ProjectMeta & { configPath: string } =>
         typeof m.configPath === 'string' && args.staged?.get(m.name) === undefined,
     )
-    const loaded = lock
-      ? withFile.length === 0
-        ? []
-        : await frozenProjectConfigs(await lock(), withFile, workspaceRoot, args.evalCache?.store)
-      : await loadProjectConfigs(
-          withFile.map((m) => m.configPath),
-          args.evalCache !== undefined ? { evalCache: args.evalCache } : {},
-        )
+    // A locked project whose config file is gone ran as locked, green,
+    // though nothing declares it any more (X-144): asked only of the
+    // configs this run reads.
+    const present = await Promise.all(withFile.map((m) => Bun.file(m.configPath).exists()))
+    const gone = withFile.find((_, i) => !present[i])
+    if (gone !== undefined) {
+      const rel = relPosix(workspaceRoot, gone.dir) || '.'
+      const named = gone.name === pathName(workspaceRoot, gone.dir) ? '' : ` ("${gone.name}")`
+      const file = relPosix(gone.dir, gone.configPath)
+      // exists() says false for a file behind a directory this user may not
+      // search too; asked only on this failure path, so a run pays no stat.
+      const denied = await stat(gone.configPath).then(
+        () => null,
+        (err: NodeJS.ErrnoException) =>
+          err.code === 'EACCES' || err.code === 'EPERM' ? err.code : null,
+      )
+      throw new UserError(
+        denied !== null
+          ? `${LOCKFILE_NAME} locks ${rel}${named}, but its ${file} is not readable by this user (${denied})`
+          : `${LOCKFILE_NAME} locks ${rel}${named}, but its ${file} is gone — run \`vx lock\``,
+      )
+    }
+    const loaded =
+      withFile.length === 0 ? [] : frozenProjectConfigs(await lock(), withFile, workspaceRoot)
     let next = 0
     for (const meta of round) {
       const pre = args.staged?.get(meta.name)
@@ -305,10 +324,15 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
             warn: args.warn,
             name: meta.name,
             dir: meta.dir,
-            packageJson: meta.packageJson as unknown as Readonly<Record<string, unknown>>,
             projects: args.projectMetas,
+            lock: args.lock === true,
           },
-          (plugin) => validateProjectConfig(config, `${where} (after plugin '${plugin.name}')`),
+          (plugin) =>
+            validateProjectConfig(
+              config,
+              `${where} (after plugin '${plugin.name}')`,
+              meta.configPath,
+            ),
         )
       }
       const built = withDefaultBuild(config)
@@ -396,57 +420,39 @@ function crossDepProjects(config: ProjectConfig): string[] {
 }
 
 /**
- * The run path's view of a workspace's projects for a reader — `vx show`,
- * the MCP server, an embedder: discovery, the plugin `config` and
- * `project` stages, and the local cache opened only to serve cached
- * evaluations, so a pure config costs a stat, not an evaluation. `scope`
- * is every project or a list of names; no closure, no lock (a reader
- * reads live, as a default run does). Plugin warnings go to `warn`.
+ * The run path's view of a workspace's projects for a reader — a plugin's
+ * verb, an embedder: the lock, the plugin `config`, `discover` and
+ * `project` stages. `scope` is every project or a list of names; no
+ * closure. No lock is `NO_LOCK`. Plugin warnings go to `warn`.
  */
 export async function loadResolvedProjects(
   workspaceRoot: string,
   opts: { scope?: 'all' | readonly string[]; warn?: (message: string) => void } = {},
 ): Promise<Map<string, ProjectEntry>> {
   const warn = opts.warn ?? ((): void => {})
-  const reads: LoadReads = new Map()
   const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, warn)
   const cacheDir = resolveCacheDir(workspaceRoot, workspaceConfig)
-  const metas = await discoverProjects(
-    await loadWorkspace(workspaceRoot, reads),
-    plugins,
+  const lock = lockReader(workspaceRoot)
+  const metas = await discoverProjects(workspaceRoot, lock, plugins, cacheDir, warn)
+  const loaded = await loadProjects({
+    workspaceRoot,
     cacheDir,
+    plugins,
+    projectMetas: metas,
+    seeds: opts.scope ?? 'all',
+    closure: false,
+    configs: lock,
     warn,
-  )
-  // Opened as `vx last` opens it: a reader makes no index where there is
-  // none and never resets an earlier schema's (C-5). One it cannot read
-  // serves nothing; the configs evaluate live.
-  let cache: Cache | undefined
-  try {
-    cache = Cache.inspect(cacheDir)
-  } catch (err) {
-    if (!(err instanceof UserError)) throw err
-  }
-  try {
-    const loaded = await loadProjects({
-      workspaceRoot,
-      cacheDir,
-      plugins,
-      projectMetas: metas,
-      seeds: opts.scope ?? 'all',
-      closure: false,
-      lock: null,
-      evalCache:
-        cache === undefined
-          ? undefined
-          : {
-              store: cache,
-              workspaceRoot,
-              workspaceFingerprint: await computeWorkspaceFingerprint(workspaceRoot, reads),
-            },
-      warn,
-    })
-    return loaded.projects
-  } finally {
-    cache?.close()
-  }
+  })
+  return loaded.projects
+}
+
+/** The lock, read once on first ask; no lock is `NO_LOCK`. */
+export function lockReader(workspaceRoot: string): () => Promise<Lockfile> {
+  let read: Promise<Lockfile> | undefined
+  return () =>
+    (read ??= readLockfile(workspaceRoot).then((lock) => {
+      if (lock === null) throw new UserError(NO_LOCK)
+      return lock
+    }))
 }

package/src/orchestrator/remote-prefetch.ts

@@ -12,8 +12,9 @@
 // GET per key.
 //
 // HARD SCOPE: this runs ONLY when a remote layer is configured. It
-// NEVER touches the local cache (no local get / no isOutputsCurrent /
-// no stat pass) — it derives keys and probes REMOTE only. Local-only
+// asks the local index only which keys it holds (no local get / no
+// isOutputsCurrent), and probes the remote for the rest: a run the local
+// cache answers makes no remote call (M, 2026-10-15). Local-only
 // runs are byte-identical to before; the caller gates on the layer's
 // own `hasRemote`, so a third-party remote layer gets the overlap too.
 // The two batch-probe hooks are OPTIONAL on the contract: a remote layer
@@ -30,7 +31,8 @@ export interface PrefetchArgs {
   /** A layer whose `hasRemote` is true — the caller's gate. */
   cache: CacheLayer
   workspaceRoot: string
-  workspaceFingerprint: string
+  /** The root files the plugins claim (`DeriveStableKeysArgs.claimedFiles`). */
+  claimedFiles: readonly string[]
   forwardArgs?: readonly string[] | undefined
   nestedDirsByProject: Map<string, string[]>
   gitFilesCache: GitFilesCache
@@ -74,8 +76,11 @@ async function runPrefetch(args: PrefetchArgs): Promise<void> {
   // would 404. When the remote can't batch (`null` — an older remote, reads
   // disabled, or a layer that doesn't implement the hook at all), fall back to
   // prefetching every stable key, exactly as before.
-  let toPrefetch = stableKeys
-  const uniqueHashes = [...new Set(stableKeys.map((k) => k.hash))]
+  const held =
+    (await args.cache.localHasMany?.([...new Set(stableKeys.map((k) => k.hash))])) ?? null
+  let toPrefetch = held === null ? stableKeys : stableKeys.filter((k) => !held.has(k.hash))
+  if (toPrefetch.length === 0) return
+  const uniqueHashes = [...new Set(toPrefetch.map((k) => k.hash))]
   const present = (await args.cache.remoteHasMany?.(uniqueHashes)) ?? null
   if (present !== null) {
     args.cache.markRemoteAbsent?.(uniqueHashes.filter((h) => !present.has(h)))
@@ -84,7 +89,7 @@ async function runPrefetch(args: PrefetchArgs): Promise<void> {
     // economy: deleting it alone GETs nothing extra, deleting both GETs
     // every absent key. What it decides is which hashes the pump asks
     // the layer for, and that is what the row pins (item 643, 645).
-    toPrefetch = stableKeys.filter((k) => present.has(k.hash))
+    toPrefetch = toPrefetch.filter((k) => present.has(k.hash))
     if (toPrefetch.length === 0) return
   }
 

package/src/orchestrator/run-context.ts

@@ -13,7 +13,8 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { executablePath, relPosix, ulid, xxh3hex } from '../util/index.js'
+import { executablePath, gitEnv, relPosix, ulid, xxh3hex } from '../util/index.js'
+import { resolveSetting } from '../settings.js'
 
 export interface GitContext {
   /** `git rev-parse HEAD`, or null outside a repo / on failure. */
@@ -86,6 +87,7 @@ export function captureGitContext(
         '--abbrev-ref',
         'HEAD',
       ],
+      env: gitEnv(),
       stdout: 'pipe',
       stderr: 'ignore',
     })
@@ -280,6 +282,7 @@ export function captureDefaultBranch(
           '--short',
           'refs/remotes/origin/HEAD',
         ],
+        env: gitEnv(),
         stdout: 'pipe',
         stderr: 'ignore',
       })
@@ -445,10 +448,10 @@ export function normalizeRemoteUrl(raw: string): string {
  * (telemetry schema v2). Derivation ladder:
  *   1. git remote origin URL, normalized → xxh3 (same id from any
  *      machine's checkout of the same repo);
- *   2. no remote → a salt persisted at `<root>/.vx/workspace-id` (the
- *      checkout keeps a stable identity across runs; `.vx/` is already
- *      gitignored infrastructure);
- *   3. unwritable `.vx/` → the root path itself (stable per machine).
+ *   2. no remote → a salt persisted at `<root>/.vx/cache/workspace-id`
+ *      (the checkout keeps a stable identity across runs; `.vx/cache` holds
+ *      the machine-local state, never committed);
+ *   3. unwritable `.vx/cache` → the root path itself (stable per machine).
  * The URL comes from the run's own `git var -l` when it has one, else one
  * `git` spawn behind try/catch; call sites gate on telemetry being active
  * so a plain run never pays it. Never throws.
@@ -473,6 +476,7 @@ export function captureWorkspaceIdentity(
         // different proxies would derive different workspace ids. The raw
         // configured URL is the identity.
         cmd: [executablePath('git'), '-C', workspaceRoot, 'config', '--get', 'remote.origin.url'],
+        env: gitEnv(),
         stdout: 'pipe',
         stderr: 'ignore',
       })
@@ -488,7 +492,7 @@ export function captureWorkspaceIdentity(
     // git unavailable — fall through to the salt.
   }
   try {
-    const saltPath = path.join(workspaceRoot, '.vx', 'workspace-id')
+    const saltPath = path.join(workspaceRoot, '.vx', 'cache', 'workspace-id')
     let salt: string
     try {
       salt = fs.readFileSync(saltPath, 'utf8').trim()
@@ -503,3 +507,18 @@ export function captureWorkspaceIdentity(
     return { id: xxh3hex(workspaceRoot), name: base, ...where }
   }
 }
+
+/**
+ * The run's branch: `run.branch` (the flag given, else `VX_RUN_BRANCH`,
+ * else the workspace's), else HEAD's, else the CI provider's for a
+ * detached checkout. What run history records and a forecast reads first.
+ */
+export function currentBranch(
+  workspaceRoot: string,
+  workspace?: unknown,
+  flag?: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  const set = resolveSetting('run.branch', workspace, flag, env).value as string | undefined
+  return set ?? captureGitContext(workspaceRoot, null, env).branch
+}

package/src/orchestrator/run-failures.ts

@@ -1,6 +1,5 @@
 // A failed run's task output and the files it names, so an agent reads why
-// a task failed without the terminal (`vx last --format json`, vx-mcp's
-// getFailures). One file per failed run, `<cacheDir>/failures/<runId>.json`,
+// a task failed without the terminal (`vx last --format json`). One file per failed run, `<cacheDir>/failures/<runId>.json`,
 // the newest 50 kept: files, not cache.db, so the index layout (and every
 // shared store under it) stays as it was.
 
@@ -21,6 +20,8 @@ export interface TaskFailure {
   taskId: string
   exitCode: number
   timedOut?: true
+  /** The input that changed while the command ran (see `TaskOutcome`). */
+  inputMoved?: string
   /** Plain text, bounded, secrets masked; '' when the run kept none. */
   output: string
   locations: OutputLocation[]
@@ -47,18 +48,25 @@ function failuresOf(outcomes: readonly TaskOutcome[]): StoredFailure[] {
   const isFile = fileMemo()
   const out: StoredFailure[] = []
   for (const o of outcomes) {
-    if (o.failedOutput === undefined || isGroupTask(o.node)) continue
-    const output = Bun.stripANSI(
-      decodeOutputLog(o.failedOutput)
-        .map((c) => c.text)
-        .join(''),
-    )
+    // A task failed by a moved input may have printed nothing: the input
+    // is still why, and an agent reads it here.
+    if ((o.failedOutput === undefined && o.inputMoved === undefined) || isGroupTask(o.node))
+      continue
+    const output =
+      o.failedOutput === undefined
+        ? ''
+        : Bun.stripANSI(
+            decodeOutputLog(o.failedOutput)
+              .map((c) => c.text)
+              .join(''),
+          )
     out.push({
       taskId: o.node.id,
       project: o.node.projectName,
       task: o.node.taskName,
       exitCode: o.exitCode,
       ...(o.timedOut === true ? { timedOut: true as const } : {}),
+      ...(o.inputMoved !== undefined ? { inputMoved: o.inputMoved } : {}),
       output,
       locations: fileLocations(output, o.node.projectDir, isFile),
       ...(o.sandboxFix !== undefined ? { sandboxFix: o.sandboxFix } : {}),
@@ -138,6 +146,7 @@ export function runFailures(cacheDir: string, db: Database, runId?: string): Run
         taskId,
         exitCode: r.exitCode,
         ...(r.timedOut === 1 ? { timedOut: true as const } : {}),
+        ...(k?.inputMoved !== undefined ? { inputMoved: k.inputMoved } : {}),
         output: k?.output ?? '',
         locations: k?.locations ?? [],
         ...(k?.sandboxFix !== undefined ? { sandboxFix: k.sandboxFix } : {}),

package/src/orchestrator/run-lock.ts

@@ -330,7 +330,7 @@ export async function acquireRunLock(
   opts: RunLockOptions,
 ): Promise<() => Promise<void>> {
   const lockDir = runLockPath(workspaceRoot, opts.dir)
-  // A task's own process (`vx cache prune` in a task) would wait for the
+  // A task's own process (`vx cache clean` in a task) would wait for the
   // run that started it, which holds the lock until that task ends.
   const outer = process.env[VX_RUN_WORKSPACE_ENV]
   if (outer !== undefined && runLockPath(outer, opts.dir) === lockDir) {

package/src/orchestrator/run-records.ts

@@ -27,7 +27,7 @@ export interface RunRecordsInput {
   ok: boolean
   command: string
   requestedTasks: readonly string[]
-  /** Already compacted (`compactCachePolicy`), the form the header row stores. */
+  /** Already formatted (`formatCachePolicy`), the form the header row stores. */
   cachePolicy: string
   concurrency: number
   flow: InvocationRecord['flow']

package/src/orchestrator/run-report.ts

@@ -82,7 +82,7 @@ function statusWord(o: OutcomeView): string {
     case 'cache-hit-remote':
       return 'success'
     case 'failed':
-      return failedLabel(o.exitCode, o.timedOut, o.sandboxViolations, o.notReady)
+      return failedLabel(o.exitCode, o.timedOut, o.sandboxViolations, o.notReady, o.inputMoved)
     case 'skipped':
       return skippedLabel(o.blockedBy)
     case 'aborted':
@@ -144,8 +144,13 @@ const cell = escapeMarkdownCell
 export function formatRunReportMarkdown(result: RunResult): string {
   const t = tally(result.outcomes)
   const cached = t.cachedLocal + t.cachedRemote
+  // The terminal summary's words and counts: every task in the run counts
+  // (M, 2026-10-14), and a task the stop reached before it ran was never
+  // aborted.
+  const aborted = t.aborted - t.notRun
+  const count = t.total + aborted + t.notRun
   const parts = [
-    `**${t.total} task${t.total === 1 ? '' : 's'}**`,
+    `**${count} task${count === 1 ? '' : 's'}**`,
     `${t.successful} success`,
     `${t.failed} failed`,
     // What the hits did to the disk, as the run's summary splits them.
@@ -154,15 +159,10 @@ export function formatRunReportMarkdown(result: RunResult): string {
       : '0 cached',
   ]
   if (t.skipped > 0) parts.push(`${t.skipped} skipped`)
+  if (aborted > 0) parts.push(`${aborted} aborted`)
+  if (t.notRun > 0) parts.push(`${t.notRun} not run`)
   parts.push(`${fmtDuration(t.executedMs)} total`)
   if (t.savedMs > 0) parts.push(`${fmtDuration(t.savedMs)} saved`)
-  // The terminal summary's words: neither is in `total`, and a task the stop
-  // reached before it ran was never aborted.
-  const aborted = t.aborted - t.notRun
-  const uncounted: string[] = []
-  if (aborted > 0) uncounted.push(`${aborted} aborted`)
-  if (t.notRun > 0) uncounted.push(`${t.notRun} not run`)
-  if (uncounted.length > 0) parts.push(`not counted: ${uncounted.join(', ')}`)
 
   // Only a stop (a signal, `RunOptions.signal`) makes an `aborted` outcome,
   // so one is how an interrupted run tells itself from a failed one.

package/src/orchestrator/run-settings.ts

@@ -0,0 +1,48 @@
+// A run's run-level settings, resolved once before any task: the flag
+// (a RunOptions field) beats its variable, which beats `.vx/workspace`
+// (src/settings.ts). A task's own `exec.timeout` / `exec.retries` is
+// applied where the task runs, above all three.
+
+import type { WorkspaceConfig } from '../config.js'
+import { resolveSetting } from '../settings.js'
+import { setSettleBounds, type SettleBound } from '../util/index.js'
+import type { RunOptions } from './options.js'
+
+const FROM_OPTIONS = {
+  concurrency: 'run.concurrency',
+  schedule: 'run.schedule',
+  timeout: 'run.timeout',
+  retries: 'run.retries',
+  continueMode: 'run.continue',
+  readyNotice: 'run.readyNotice',
+  download: 'cache.download',
+} as const satisfies Partial<Record<keyof RunOptions, string>>
+
+/**
+ * `options` with each run-level setting it leaves unset filled from the
+ * environment, then the workspace. Arms the settle bounds (`util/settle`,
+ * below settings) with the flag's or workspace's `run.killGrace` and
+ * `run.teardownTimeout`: the variable sits between them, read per call.
+ */
+export function withRunSettings(
+  options: RunOptions,
+  workspace: WorkspaceConfig | null | undefined,
+): RunOptions {
+  const out: Record<string, unknown> = { ...options }
+  for (const [field, path] of Object.entries(FROM_OPTIONS)) {
+    const { value } = resolveSetting(path, workspace, options[field as keyof RunOptions])
+    if (value !== undefined) out[field] = value
+  }
+  const bound = (flag: number | undefined, path: string): SettleBound | undefined => {
+    if (flag !== undefined) return { ms: flag, from: 'flag' }
+    const { value } = resolveSetting(path, workspace, undefined, {})
+    return value === undefined ? undefined : { ms: value as number, from: 'workspace' }
+  }
+  const killGrace = bound(options.killGrace, 'run.killGrace')
+  const teardown = bound(options.teardownTimeout, 'run.teardownTimeout')
+  setSettleBounds({
+    ...(killGrace !== undefined ? { killGrace } : {}),
+    ...(teardown !== undefined ? { teardown } : {}),
+  })
+  return out as unknown as RunOptions
+}