@vzn/vx 0.0.637 → 0.0.639

package/src/{orchestrator → history}/metrics.ts

@@ -15,11 +15,13 @@ import { statSync } from 'node:fs'
 import path from 'node:path'
 // The keyed-run predicate lives beside the schema in cache/cache.ts, so a
 // rule written once cannot drift.
-import { KEYED_RUNS_SQL } from '../cache/index.js'
-import { splitTaskId } from '../graph/index.js'
+import { KEYED_RUNS_SQL, type TaskInputComponent } from '../cache/index.js'
+import { isPassStatus, splitTaskId } from '../graph/index.js'
 import { clampInt, MASKED, secretNamed } from '../util/index.js'
-import type { TaskInputComponent } from './task-hash.js'
-import { isPassStatus } from './telemetry.js'
+
+// A recorded `cache_policy` is the `--cache-policy` spec (`local:rw,remote:r`).
+const readsCache = (spec: string): boolean => /(?:^|,)(?:local|remote):w?r/.test(spec)
+const writesCache = (spec: string): boolean => /(?:^|,)(?:local|remote):r?w/.test(spec)
 
 // ---------------------------------------------------------------------------
 // Run listing + detail
@@ -53,6 +55,8 @@ export interface RunSummaryRow {
   notReady: 'timeout' | 'exited' | 'spawn' | null
   /** The task ran with the run's forwarded args (`-- …`): a requested one under a run that had some. */
   forwarded: boolean
+  /** Each remote read or write of its key that failed, `upload: <message>`, `; `-joined (v40). */
+  remoteError: string | null
 }
 
 export interface ListRunsArgs {
@@ -113,7 +117,7 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
               wallclock_start_ns AS wallclockStartNs, wallclock_end_ns AS wallclockEndNs,
               blocked_by AS blockedBy, timed_out AS timedOut,
               sandbox_violations AS sandboxViolations, not_ready AS notReady,
-              forward_args IS NOT NULL AS forwarded
+              forward_args IS NOT NULL AS forwarded, remote_error AS remoteError
        FROM runs ${clause} ORDER BY id DESC LIMIT ?`,
     )
     .all(...params, limit) as RawRow[]
@@ -131,8 +135,7 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
 
 /**
  * One `vx run` invocation header — every `invocations` column, camelCased,
- * `tags` parsed to a `Record<string,string>` and `dirty`/`ci`/`exitOk`
- * surfaced as booleans. The SPA's
+ * `dirty`/`ci`/`exitOk` surfaced as booleans. The SPA's
  * existing fields (runId / startedAt / endedAt / taskCount / failedCount /
  * hitCount / totalDurationMs) are all present, so existing views keep working.
  */
@@ -166,7 +169,6 @@ export interface InvocationDetail {
   os: string | null
   arch: string | null
   vxVersion: string
-  tags: Record<string, string>
 }
 
 interface InvocationRawRow {
@@ -197,7 +199,6 @@ interface InvocationRawRow {
   os: string | null
   arch: string | null
   vxVersion: string
-  tags: string
 }
 
 const INVOCATION_COLUMNS = `
@@ -210,7 +211,7 @@ const INVOCATION_COLUMNS = `
   restored_remote_count AS restoredRemoteCount,
   exit_ok AS exitOk,
   commit_sha AS commitSha, branch, dirty, ci, ci_provider AS ciProvider,
-  host, os, arch, vx_version AS vxVersion, tags`
+  host, os, arch, vx_version AS vxVersion`
 
 function mapInvocation(r: InvocationRawRow): InvocationDetail {
   let requestedTasks: string[] = []
@@ -218,15 +219,6 @@ function mapInvocation(r: InvocationRawRow): InvocationDetail {
     const parsed = JSON.parse(r.requestedTasks) as unknown
     if (Array.isArray(parsed)) requestedTasks = parsed.map(String)
   } catch {}
-  let tags: Record<string, string> = {}
-  try {
-    const parsed = JSON.parse(r.tags) as unknown
-    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
-      tags = Object.fromEntries(
-        Object.entries(parsed as Record<string, unknown>).map(([k, v]) => [k, String(v)]),
-      )
-    }
-  } catch {}
   return {
     runId: r.runId,
     command: r.command,
@@ -255,7 +247,6 @@ function mapInvocation(r: InvocationRawRow): InvocationDetail {
     os: r.os,
     arch: r.arch,
     vxVersion: r.vxVersion,
-    tags,
   }
 }
 
@@ -412,7 +403,7 @@ function unchangedKeyNote(
       p: string
     } | null
   )?.p
-  if (policy !== undefined && !policy.split(',').some((axis) => axis === 'lR' || axis === 'rR')) {
+  if (policy !== undefined && !readsCache(policy)) {
     return 'cache key unchanged — re-executed because this run did not read the cache (--force, or a --cache-policy without read)'
   }
   // `get` answers null, not undefined, for no row.
@@ -438,7 +429,7 @@ function unchangedKeyNote(
       const row = db
         .query('SELECT cache_policy AS p, failed_count AS f FROM invocations WHERE run_id = ?')
         .get(id) as { p: string; f: number } | null
-      const writes = row?.p.split(',').some((axis) => axis === 'lW' || axis === 'rW') === true
+      const writes = row !== null && writesCache(row.p)
       return writes ? (row?.f ?? 0) : 0
     }
     const before = failedWithWrites(prev.runId)
@@ -472,7 +463,7 @@ function unchangedKeyNote(
               p: string
             } | null
           )?.p
-    if (prevPolicy !== undefined && !prevPolicy.split(',').some((a) => a === 'lW' || a === 'rW')) {
+    if (prevPolicy !== undefined && !writesCache(prevPolicy)) {
       return 'cache key unchanged — the previous run on this key did not write the cache (--no-cache, or a --cache-policy without write), so there was nothing to hit'
     }
     return 'cache key unchanged — the previous run on this key executed but no entry for it is in the cache (its save failed, or it was pruned since), so there was nothing to hit'

package/src/{orchestrator → history}/miss-reason.ts

@@ -9,7 +9,7 @@
 import type { Database } from 'bun:sqlite'
 import type { InputChanges } from '../graph/index.js'
 import { diffKeyComponents, loadEntryInputs } from './metrics.js'
-import type { TaskInputComponent } from './task-hash.js'
+import type { TaskInputComponent } from '../cache/index.js'
 
 /** How many changed components a miss names; `count` says how many there were. */
 const NAMED = 10

package/src/index.ts

@@ -56,13 +56,9 @@ export { run, planRun, prepareRun } from './orchestrator/index.js'
 // The per-task duration history a `schedule` plugin learns from
 // (`@vzn/vx-schedule-history` does; a plugin package reaches core only
 // through this façade, which is what put these here).
-export { currentBranch, LocalHistoryProvider } from './orchestrator/index.js'
-export type {
-  HistoryProvider,
-  HistoryTable,
-  TaskHistory,
-  TaskResources,
-} from './orchestrator/index.js'
+export { currentBranch } from './orchestrator/index.js'
+export { LocalHistoryProvider } from './history/index.js'
+export type { HistoryProvider, HistoryTable, TaskHistory, TaskResources } from './history/index.js'
 export type { PreparedRun } from './orchestrator/index.js'
 // `RunOptions.affected`: what `--affected`'s diff changed, per project.
 export type { AffectedChanges } from './workspace/index.js'
@@ -72,14 +68,8 @@ export type { AffectedChanges } from './workspace/index.js'
 // docs/cli.md § Programmatic API listed all three (item 387, 2026-09-19).
 export type { RunPlan, PlannedTask } from './orchestrator/index.js'
 export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './orchestrator/index.js'
-export type {
-  CacheFlags,
-  CachePolicy,
-  Logger,
-  OutputView,
-  RunOptions,
-  RunSummary,
-} from './orchestrator/index.js'
+export type { CacheFlags, CachePolicy, RunOptions, RunSummary } from './orchestrator/index.js'
+export type { Logger, OutputView } from './report/index.js'
 // `splitTaskId` is on the façade because the alternative is what happened:
 // with only `taskId()` to JOIN an id and nothing exported to SPLIT one,
 // consumers roll their own `split('#', 2)` and drift from the graph, which
@@ -89,7 +79,13 @@ export type { TaskNode, TaskOutcome, TaskStatus } from './graph/index.js'
 
 // Cache classes + the layer interface (the `cache` capability's currency).
 export { Cache } from './cache/index.js'
-export type { CacheLayer, RemoteCacheLayer, RunRecord, InvocationRecord } from './cache/index.js'
+export type {
+  CacheLayer,
+  PluginCache,
+  RemoteCacheLayer,
+  RunRecord,
+  InvocationRecord,
+} from './cache/index.js'
 
 // Workspace discovery + the project/config catalog surface — an
 // out-of-process service/CLI needs these. `loadProjectConfig` is the RAW
@@ -118,6 +114,8 @@ export {
   quoteTsLiteral,
   taskNameProblem,
 } from './workspace/index.js'
+// Output components: a plugin draws its lines with core's, so they look alike.
+export { ui } from './util/index.js'
 export type {
   ApplyMigrationArgs,
   MigrationFormat,
@@ -166,10 +164,12 @@ export type {
   DiscoverContext,
   DiscoveredProject,
   PluginSetupContext,
+  RunReport,
+  RunReportTask,
   PluginHookName,
   PluginHookHandlers,
-  RunStartInfo,
 } from './orchestrator/index.js'
+export type { RunStartInfo } from './report/index.js'
 // The per-task execution contract a plugin's `executor` capability returns.
 // (`runCommand` / `runSandboxed`, the local executor's own primitives, left
 // the façade 2026-09-10: no executor plugin built on them — `@vzn/vx-reapi`
@@ -201,15 +201,8 @@ export type {
 // consumer rolls its own Set of status literals — and a Set has no
 // compile-time tripwire when the union gains a member, so it silently answers
 // "no" for the new one.
-// `escapeMarkdownCell` is on the façade for the same demonstrated need: a
-// plugin that renders a run as a markdown table takes the same unvalidated
-// task names core does, and the cloud job summary shipped without the escape.
-export {
-  escapeMarkdownCell,
-  TELEMETRY_SCHEMA_VERSION,
-  isCacheHit,
-  isPassStatus,
-} from './orchestrator/index.js'
+export { type CacheSource, isCacheHit, isPassStatus } from './graph/index.js'
+export { TELEMETRY_SCHEMA_VERSION } from './orchestrator/index.js'
 // `TaskLogBuffer` is on the façade on the same demonstrated need: EVERY
 // telemetry sink that ships build output has to bound it, and the retention
 // rules (per-task tail, per-run budget, failures never evicted by successes,
@@ -221,7 +214,6 @@ export { LOG_WIRE_VERSION, TaskLogBuffer } from './orchestrator/index.js'
 // say `128 + SIGKILL`; the decode is the runner's convention, one copy.
 export { exitSignal } from './orchestrator/index.js'
 export type {
-  CacheSource,
   RunContextRecord,
   RunSummaryRecord,
   TaskLogBundle,
@@ -232,5 +224,5 @@ export type {
   TelemetrySink,
 } from './orchestrator/index.js'
 
-// The serializable run result and its per-task views (what `run()` returns).
-export type { RunResult, TaskView, OutcomeView } from './orchestrator/index.js'
+// The serializable per-task views.
+export type { TaskView, OutcomeView } from './report/index.js'

package/src/orchestrator/affected-tasks.ts

@@ -62,13 +62,15 @@ function wholeProjects(
  * `input`, a changed `file` is one of its declared inputs; `project`, its
  * project changed and the task reads it whole (an uncached task, a path no
  * cached task declares, or no single `file`: a lockfile claim, a manifest
- * edge, a config import); `package`, a `^` edge passes through `project`, a
+ * edge, a config import); `workspace`, a workspace-wide `file` (the
+ * workspace config, a root file a plugin claims) reached every task of its
+ * project; `package`, a `^` edge passes through `project`, a
  * changed package with no such task; `named`, asked as `pkg#task`;
  * `selected`, another filter selected its project outright. `via` is the
  * `dependsOn` chain, nearest first, to the task the change seeded.
  */
 export interface AffectedReason {
-  kind: 'input' | 'project' | 'package' | 'named' | 'selected'
+  kind: 'input' | 'project' | 'workspace' | 'package' | 'named' | 'selected'
   /** Workspace-relative. */
   file?: string
   project?: string
@@ -102,7 +104,10 @@ export function affectedRoots(
   const seeds = explain === undefined ? null : new Map<string, AffectedReason>()
   const through = explain === undefined ? null : new Map<string, string>()
   const inProject = (name: string, rel: string | undefined): AffectedReason => {
-    if (rel === undefined) return { kind: 'project' }
+    if (rel === undefined) {
+      const file = changes.wholeBy?.get(name)
+      return file === undefined ? { kind: 'project' } : { kind: 'workspace', file }
+    }
     const dir = path.relative(explain!.workspaceRoot, projects.get(name)!.dir)
     return { kind: 'project', file: dir === '' ? rel : path.posix.join(dir, rel) }
   }

package/src/orchestrator/doctor.ts

@@ -30,7 +30,7 @@ import {
   resolveCacheDir,
   resolveStoreRoot,
 } from '../workspace/index.js'
-import { flakyTasks, type FlakyTask } from './failure-mode.js'
+import { flakyTasks, type FlakyTask } from '../history/index.js'
 import type { VxPlugin } from './plugin.js'
 import { discoverProjects, loadProjects, loadWorkspacePlugins, lockReader } from './projects.js'
 import { atPath, envName, resolveSetting, SETTINGS, type SettingSource } from '../settings.js'
@@ -384,7 +384,7 @@ function gitVersion(): string | null {
 function settingsFact(config: WorkspaceConfig | null): InfoFacts['settings'] {
   const out: InfoFacts['settings'] = {}
   for (const s of SETTINGS) {
-    const env = process.env[envName(s.path)]
+    const env = s.env === false ? undefined : process.env[envName(s.path)]
     const declared = s.config === false ? undefined : atPath(config, s.path)
     out[s.path] =
       env !== undefined && env !== ''

package/src/orchestrator/execute-args.ts

@@ -0,0 +1,80 @@
+// What a dispatch hands executeTask: the run's half, built once, and the
+// task's half, looked up per dispatch. The run's half is one fixed-shape
+// object every task spreads; the task's optional fields are assigned only
+// when present: twelve conditional spreads per task cost ~18 ms of object
+// copying on a 1,090-package warm run (X-149).
+
+import type { TaskNode, TaskOutcome } from '../graph/index.js'
+import type { Logger } from '../report/index.js'
+import type { DownloadMode } from './download-policy.js'
+import type { ExecuteArgs } from './execute-task.js'
+import type { ShortCircuit } from './local-shortcircuit.js'
+import { UNPLACED_EXECUTOR, type Placements } from './placement.js'
+
+type TaskField =
+  | 'node'
+  | 'upstream'
+  | 'log'
+  | 'executor'
+  | 'nestedProjectDirs'
+  | 'remoteOnlyNoop'
+  | 'remoteOnly'
+  | 'download'
+  | 'preProbed'
+  | 'upfrontKey'
+  | 'upfrontGroupKey'
+  | 'taintedUpstream'
+  | 'noDependants'
+  | 'terminal'
+
+/** What every task of a run shares; an absent optional stays absent. */
+export type RunScope = Omit<ExecuteArgs, TaskField>
+
+/** Where the task's half is read from, per task id. */
+export interface TaskFacts {
+  log: (node: TaskNode) => Logger
+  placements: Placements
+  nestedDirsByProject: ReadonlyMap<string, string[]>
+  downloadModeOf: ReadonlyMap<string, DownloadMode>
+  shortCircuit: Pick<ShortCircuit, 'preProbed' | 'uncachedKeys' | 'groupKeys'>
+  /** Tasks some other task depends on. */
+  dependedOn: ReadonlySet<string>
+  /** Tasks that hold the terminal (`terminalHolders`). */
+  holders: ReadonlySet<string>
+}
+
+/**
+ * The dispatch builder. `reuseProbe: false` takes the task's key again
+ * instead of the up-front probe (admission's retry after a dropped probe);
+ * `tainted` is the run's taint verdict for this dispatch.
+ */
+export function executeArgsOf(
+  scope: RunScope,
+  facts: TaskFacts,
+): (node: TaskNode, upstream: TaskOutcome[], reuseProbe: boolean, tainted: boolean) => ExecuteArgs {
+  const { placements, shortCircuit } = facts
+  return (node, upstream, reuseProbe, tainted) => {
+    const id = node.id
+    const a: ExecuteArgs = {
+      ...scope,
+      node,
+      upstream,
+      log: facts.log(node),
+      executor: placements.executors.get(id) ?? UNPLACED_EXECUTOR,
+      nestedProjectDirs: facts.nestedDirsByProject.get(node.projectName) ?? [],
+    }
+    const probe = reuseProbe ? shortCircuit.preProbed.get(id) : undefined
+    const upfrontKey = shortCircuit.uncachedKeys.get(id)
+    const upfrontGroupKey = shortCircuit.groupKeys.get(id)
+    if (facts.downloadModeOf.get(id) === 'deferred') a.download = 'deferred'
+    if (placements.remoteOnlyNoop.has(id)) a.remoteOnlyNoop = true
+    if (placements.remoteOnly.has(id)) a.remoteOnly = true
+    if (probe !== undefined) a.preProbed = probe
+    if (upfrontKey !== undefined) a.upfrontKey = upfrontKey
+    if (upfrontGroupKey !== undefined) a.upfrontGroupKey = upfrontGroupKey
+    if (tainted) a.taintedUpstream = true
+    if (!facts.dependedOn.has(id)) a.noDependants = true
+    if (facts.holders.has(id)) a.terminal = true
+    return a
+  }
+}