@vzn/vx 0.0.16 → 0.0.18

package/src/orchestrator/prepare.ts

@@ -9,7 +9,7 @@
 
 import path from 'node:path'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
-import { UserError } from '../util/index.js'
+import { mark, UserError } from '../util/index.js'
 import {
   Cache,
   type CacheLayer,
@@ -17,7 +17,10 @@ import {
   FULL_CACHE_POLICY,
   GitFilesCache,
   LayeredCache,
-  populateGitFilesCache,
+  applyGitEnumeration,
+  gitPathspecs,
+  startGitEnumeration,
+  type GitEnumeration,
 } from '../cache/index.js'
 import {
   buildPackageGraph,
@@ -26,25 +29,40 @@ import {
   findWorkspaceRoot,
   frozenProjectConfig,
   listProjects,
-  loadProjectConfig,
+  loadProjectConfigs,
   loadWorkspace,
   loadWorkspaceConfig,
   readLockfile,
   resolveCacheDir,
+  validateProjectConfig,
   type ProjectEntry,
 } from '../workspace/index.js'
-import { buildTaskGraph, expandRequested, type TaskNode } from '../graph/index.js'
-import { resolveCache } from './plugin-host.js'
+import {
+  buildTaskGraph,
+  expandRequested,
+  parseDependencySpec,
+  type TaskNode,
+  unresolvedRequests,
+} from '../graph/index.js'
+import {
+  applyConfigHooks,
+  applyGraphHooks,
+  applyKeyHooks,
+  applyProjectHooks,
+  applyScheduleHooks,
+  hasHook,
+  resolveCache,
+} from './plugin-host.js'
 import type { VxPlugin } from './plugin.js'
 import { createHashCache, type HashCache } from './task-hash.js'
 import type { Logger } from './logger.js'
 import type { RunOptions } from './options.js'
-import { type HistoryTable, LocalHistoryProvider } from './history.js'
-import { computePredictedPriorities } from './predict.js'
 
 export interface PreparedRun {
   workspaceRoot: string
   workspaceConfig: WorkspaceConfig | null
+  /** The workspace's declared plugins, in declaration order. Nothing is added. */
+  plugins: readonly VxPlugin[]
   cacheDir: string
   cache: CacheLayer
   /**
@@ -54,12 +72,30 @@ export interface PreparedRun {
    */
   localCache: Cache
   /**
-   * Predicted priorities (history-aware critical-path). Populated only
-   * when the workspace opts in via `defineWorkspace({ predictive: true })`.
-   * Empty map otherwise — scheduler falls back to its baseline.
+   * True when `cache` is something other than the bare local handle — an
+   * injected remote layer, or one a plugin's `cache` capability built. The
+   * remote axes of the policy only mean anything then: without a remote
+   * layer a `remote:w` policy writes NOWHERE, so a task that believed it
+   * would be saved still cleans its outputs before executing and (under
+   * `--verify`) restores an artifact that was never written.
+   */
+  hasRemoteLayer: boolean
+  /**
+   * Scheduling priorities from plugins' `schedule` stage (task id → weight,
+   * merged over the structural baseline by the scheduler). Empty when no
+   * plugin declares the stage.
    */
   priorities: ReadonlyMap<string, number>
   nodes: Map<string, TaskNode>
+  /**
+   * Requested task specs that matched NO project — a typo, or a stray
+   * positional (the value of an `=`-only flag written with a space).
+   * Nothing they asked for is in `nodes`, so callers must fail rather
+   * than run the remainder silently.
+   */
+  unresolvedTasks: readonly string[]
+  /** Every discovered project — the declared task names a typo is measured against. */
+  projects: ReadonlyMap<string, ProjectEntry>
   workspaceFingerprint: string
   nestedDirsByProject: Map<string, string[]>
   /**
@@ -93,6 +129,25 @@ export interface PreparedRun {
   empty: null | 'no-tasks-declared' | 'empty-graph'
 }
 
+/** Project names named by a `pkg#task` dependsOn entry anywhere in `config`. */
+function crossDepProjects(config: ProjectConfig): string[] {
+  const out: string[] = []
+  for (const task of Object.values(config.tasks ?? {})) {
+    for (const raw of task.dependsOn ?? []) {
+      // A malformed spec is the graph builder's error to report — it names
+      // the offending task. Here it just contributes no project.
+      if (!raw.includes('#')) continue
+      try {
+        const spec = parseDependencySpec(raw)
+        if (spec.kind === 'cross') out.push(spec.project)
+      } catch {
+        continue
+      }
+    }
+  }
+  return out
+}
+
 /**
  * Build the prepared-run context: workspace discovery, project-config
  * load, package + task graph, cache handle (local, optionally wrapped
@@ -104,19 +159,47 @@ export interface PreparedRun {
  * empty plan).
  */
 export async function prepareRun(options: RunOptions, log: Logger): Promise<PreparedRun> {
+  mark('startup')
   const workspaceRoot = await findWorkspaceRoot(options.cwd)
+  // An UNSCOPED run (no explicit scope, at least one bare task name)
+  // enumerates the whole tree whatever the configs say, so git starts
+  // HERE — the walk needs only the root — and overlaps the workspace
+  // config, discovery, the cache open and the config evaluation. Its
+  // ~60 ms is the warm run's wall floor on a 1000-project tree; it used to
+  // start after discovery and the cache open, ~25 ms later. A scoped run
+  // waits: its pathspecs depend on which projects the configs pull in.
+  const unscoped =
+    options.projects === undefined && options.tasks.some((spec) => spec.indexOf('#') <= 0)
+  const earlyGit: Promise<GitEnumeration> | undefined = unscoped
+    ? startGitEnumeration(workspaceRoot, ['.'])
+    : undefined
+  // A broken config below throws before this is awaited; the detached
+  // handler keeps that from surfacing as an unhandled rejection (the real
+  // await further down still sees the error).
+  earlyGit?.catch(() => {})
   const workspace = await loadWorkspace(workspaceRoot)
   const workspaceConfig = await loadWorkspaceConfig(workspaceRoot)
+  // The `config` stage runs before anything is derived from the workspace
+  // config; the plugin list itself is already fixed.
+  const plugins = (workspaceConfig?.plugins ?? []) as readonly VxPlugin[]
+  if (workspaceConfig !== null && hasHook(plugins, 'config')) {
+    await applyConfigHooks(plugins, workspaceConfig, {
+      workspaceRoot,
+      warn: (m) => log.status(m),
+    })
+  }
+  mark('workspace config')
   const projectMetas = await listProjects(workspace)
+  mark('discover projects')
 
   // SCOPED config loading: configs are programs, and evaluating 1090
   // of them costs ~200 ms — the dominant fixed cost of small runs.
-  // Only the in-scope projects and their transitive dependency
-  // closure can contribute graph nodes (frontier '^task' expansion
-  // never escapes the closure), so only those configs are evaluated.
-  // Side effect, deliberate and Turbo-like: a broken config in an
-  // unrelated package no longer fails a scoped run — it surfaces
-  // when that package enters a run's scope.
+  // Only the in-scope projects, their transitive dependency closure
+  // (which bounds '^task' frontier expansion) and any project named by
+  // a `pkg#task` dependsOn entry can contribute graph nodes, so only
+  // those configs are evaluated. Side effect, deliberate and
+  // Turbo-like: a broken config in an unrelated package no longer
+  // fails a scoped run — it surfaces when that package enters scope.
   const packageGraph = buildPackageGraph(projectMetas)
   const projectsWithConfigs = projectMetas.filter(
     (m): m is typeof m & { configPath: string } =>
@@ -146,13 +229,35 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   for (const project of anchored) {
     if (haveConfig.has(project)) seeds.add(project)
   }
-  const needed = new Set<string>(seeds)
-  for (const seed of seeds) {
-    for (const dep of packageGraph.transitiveDeps(seed)) needed.add(dep)
+
+  // The local cache opens BEFORE the configs load: it is also where their
+  // cached evaluations live. `--cache-dir <path>` (RunOptions.cacheDir)
+  // overrides the workspace `cacheDir` field + the `.vx/cache` default;
+  // resolved relative to cwd.
+  const policy: CachePolicy = options.cache ?? FULL_CACHE_POLICY
+  const cacheDir = options.cacheDir
+    ? path.resolve(options.cwd, options.cacheDir)
+    : resolveCacheDir(workspaceRoot, workspaceConfig)
+  const localCache = new Cache(cacheDir, { read: policy.localRead, write: policy.localWrite })
+  const workspaceFingerprint = await computeWorkspaceFingerprint(workspaceRoot)
+  mark('open cache')
+
+  type ConfigMeta = (typeof projectsWithConfigs)[number]
+  const metaByName = new Map<string, ConfigMeta>(projectsWithConfigs.map((m) => [m.name, m]))
+  const needed = new Set<string>()
+  const pending: ConfigMeta[] = []
+  const consider = (name: string): void => {
+    if (needed.has(name)) return
+    needed.add(name)
+    const meta = metaByName.get(name)
+    if (meta) pending.push(meta)
+  }
+  const considerWithDeps = (name: string): void => {
+    consider(name)
+    for (const dep of packageGraph.transitiveDeps(name)) consider(dep)
   }
+  for (const seed of seeds) considerWithDeps(seed)
 
-  const projects = new Map<string, ProjectEntry>()
-  const toLoad = projectsWithConfigs.filter((m) => needed.has(m.name))
   // Frozen mode (--frozen, CI): configs load FROM vx-lock.json after a
   // content-hash tripwire — no evaluation; env-dependent configs keep
   // their locked values. Default (local) runs ALWAYS evaluate live:
@@ -166,16 +271,52 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       `--frozen requires vx-lock.json at the workspace root — run 'vx lock' and commit it`,
     )
   }
-  const configs = await Promise.all(
-    toLoad.map((m) =>
-      lock ? frozenProjectConfig(lock, m, workspaceRoot) : loadProjectConfig(m.configPath),
-    ),
-  )
-  for (let i = 0; i < toLoad.length; i++) {
-    const meta = toLoad[i]!
-    const config = configs[i] as ProjectConfig
-    projects.set(meta.name, { name: meta.name, dir: meta.dir, config })
+
+  // Load in rounds to a fixpoint. A `pkg#task` dependsOn entry names a
+  // project the PACKAGE graph cannot reach (the cross form ignores npm
+  // 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.
+  const projects = new Map<string, ProjectEntry>()
+  const projectStage = hasHook(plugins, 'project')
+  try {
+    while (pending.length > 0) {
+      const round = pending.splice(0, pending.length)
+      const configs = lock
+        ? await Promise.all(round.map((m) => frozenProjectConfig(lock, m, workspaceRoot)))
+        : await loadProjectConfigs(
+            round.map((m) => m.configPath),
+            { evalCache: { store: localCache, workspaceFingerprint } },
+          )
+      for (let i = 0; i < round.length; i++) {
+        const meta = round[i]!
+        const config = configs[i] as ProjectConfig
+        if (projectStage) {
+          // The `project` stage edits the validated object in place; core
+          // then re-validates so a plugin can only produce what the loader
+          // accepts from a user. The message names the config file — the
+          // plugin's edit is a defect in THAT project's tasks.
+          await applyProjectHooks(plugins, config, {
+            workspaceRoot,
+            cacheDir,
+            warn: (m) => log.status(m),
+            name: meta.name,
+            dir: meta.dir,
+            packageJson: meta.packageJson as unknown as Readonly<Record<string, unknown>>,
+          })
+          validateProjectConfig(config, `${meta.configPath} (after plugins)`)
+        }
+        projects.set(meta.name, { name: meta.name, dir: meta.dir, config })
+        for (const name of crossDepProjects(config)) considerWithDeps(name)
+      }
+    }
+  } catch (err) {
+    // The cache opened before the configs loaded (it holds their cached
+    // evaluations); a config error must not leak the handle.
+    localCache.close()
+    throw err
   }
+  mark('load configs')
 
   // Boundary geometry considers every config-bearing project in the
   // workspace, loaded or not — an out-of-scope nested project must
@@ -189,14 +330,8 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     : [...projects.keys()]
 
   const requested = expandRequested(options.tasks, candidateProjects, projects)
+  const unresolvedTasks = unresolvedRequests(options.tasks, candidateProjects, projects)
 
-  const policy: CachePolicy = options.cache ?? FULL_CACHE_POLICY
-  // `--cache-dir <path>` (RunOptions.cacheDir) overrides the workspace
-  // `cacheDir` field + the `.vx/cache` default; resolved relative to cwd.
-  const cacheDir = options.cacheDir
-    ? path.resolve(options.cwd, options.cacheDir)
-    : resolveCacheDir(workspaceRoot, workspaceConfig)
-  const localCache = new Cache(cacheDir, { read: policy.localRead, write: policy.localWrite })
   // Cache seam precedence: an EXPLICITLY injected remote layer
   // (RunOptions.remoteCache — a distribution agent or serve that already
   // holds a wire client) wins outright; else a plugin's `cache` capability;
@@ -204,20 +339,26 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // cache is a plugin concern (native-cache-wire-2026-07). Injection
   // winning prevents double-wrapping when the workspace also declares a
   // cache plugin.
-  const plugins = (workspaceConfig?.plugins ?? []) as readonly VxPlugin[]
   const cache = options.remoteCache
     ? new LayeredCache(localCache, options.remoteCache, {
         policy,
         onRemoteError: (err) => log.status(`[vx] remote cache: ${err.message}`),
       })
-    : await resolveCache(
-        plugins,
+    : await resolveCache(plugins, {
+        workspaceRoot,
+        cacheDir,
+        warn: (m) => log.status(m),
         localCache,
-        { workspaceRoot, cacheDir, warn: (m) => log.status(m), localCache, policy },
-        log,
-        () => localCache,
-      )
-  const workspaceFingerprint = await computeWorkspaceFingerprint(workspaceRoot)
+        policy,
+      })
+  // Ask the LAYER, don't infer. Identity against `localCache` answers a
+  // DIFFERENT question — "did the plugin hand back something other than the
+  // handle I passed in?" — which an ordinary pass-through decorator (a
+  // metrics wrapper, a cache-dir redirect) with no remote at all answers
+  // yes to, skipping the remote-axis clamp below. `hasRemote` is the
+  // layer's own truthful answer; `LayeredCache` sets it, a bare `Cache`
+  // doesn't, and a third-party layer opts in when it really has a remote.
+  const hasRemoteLayer = cache.hasRemote === true
 
   const gitFilesCache = new GitFilesCache()
   // Bulk-populate via a single `git ls-files` at the workspace root —
@@ -231,12 +372,14 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       (t) => (t.cache?.inputs.workspaceFiles?.length ?? 0) > 0,
     ),
   )
-  await populateGitFilesCache(
-    workspaceRoot,
-    [...projects.values()].map((p) => p.dir),
-    gitFilesCache,
-    usesWorkspaceInputs,
-  )
+  const projectDirs = [...projects.values()].map((p) => p.dir)
+  const enumeration = await (earlyGit ??
+    startGitEnumeration(
+      workspaceRoot,
+      gitPathspecs(workspaceRoot, projectDirs, usesWorkspaceInputs),
+    ))
+  applyGitEnumeration(enumeration, workspaceRoot, projectDirs, gitFilesCache, usesWorkspaceInputs)
+  mark('git enumeration')
   const hashCache = createHashCache()
 
   // Empty-cases bookkeeping. We still construct the cache + fingerprint
@@ -245,11 +388,15 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     return {
       workspaceRoot,
       workspaceConfig,
+      plugins,
       cacheDir,
       cache,
       localCache,
+      hasRemoteLayer,
       priorities: new Map(),
       nodes: new Map(),
+      unresolvedTasks,
+      projects,
       workspaceFingerprint,
       nestedDirsByProject,
       gitFilesCache,
@@ -267,35 +414,39 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       ? { excludeDependencies: options.excludeDependencies }
       : {}),
   })
-
-  // Predictive scheduling (architecture-review §8.4 / Phase 4): when
-  // the workspace opts in via `predictive: true`, load history for
-  // every node in the graph + compute expected-critical-path weights.
-  // The scheduler applies them on top of the static baseline. Failing
-  // open: any error in history loading degrades to baseline-only,
-  // never to a broken run.
+  if (hasHook(plugins, 'graph')) {
+    await applyGraphHooks(plugins, nodes, {
+      workspaceRoot,
+      cacheDir,
+      warn: (m) => log.status(m),
+      requested: [...nodes.values()].filter((n) => n.requested).map((n) => n.id),
+    })
+  }
+  if (hasHook(plugins, 'key')) {
+    await applyKeyHooks(plugins, nodes, { workspaceRoot, cacheDir, warn: (m) => log.status(m) })
+  }
   let priorities: ReadonlyMap<string, number> = new Map()
-  if (workspaceConfig?.predictive === true) {
-    const history = new LocalHistoryProvider(localCache.dbHandle())
-    try {
-      const ids = [...nodes.keys()]
-      const table: HistoryTable = await history.loadFor(ids)
-      priorities = computePredictedPriorities([...nodes.values()], table)
-    } catch (err) {
-      log.status(
-        `[vx] predictive scheduling fell back to baseline: ${err instanceof Error ? err.message : String(err)}`,
-      )
-    }
+  if (hasHook(plugins, 'schedule')) {
+    priorities = await applyScheduleHooks(plugins, nodes, {
+      workspaceRoot,
+      cacheDir,
+      warn: (m) => log.status(m),
+      localCache,
+    })
   }
 
   return {
     workspaceRoot,
     workspaceConfig,
+    plugins,
     cacheDir,
     cache,
     localCache,
+    hasRemoteLayer,
     priorities,
     nodes,
+    unresolvedTasks,
+    projects,
     workspaceFingerprint,
     nestedDirsByProject,
     gitFilesCache,

package/src/orchestrator/remote-prefetch.ts

@@ -14,17 +14,20 @@
 // 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
-// runs are byte-identical to before; the caller gates on `cache
-// instanceof LayeredCache`.
+// 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
+// that implements neither still prefetches, per-hash.
 
 import type { TaskNode } from '../graph/index.js'
-import type { GitFilesCache, LayeredCache } from '../cache/index.js'
+import type { CacheLayer, GitFilesCache } from '../cache/index.js'
 import type { HashCache } from './task-hash.js'
 import { deriveStableKeys } from './stable-keys.js'
 
 export interface PrefetchArgs {
   nodes: Map<string, TaskNode>
-  cache: LayeredCache
+  /** A layer whose `hasRemote` is true — the caller's gate. */
+  cache: CacheLayer
   workspaceRoot: string
   workspaceFingerprint: string
   forwardArgs?: readonly string[] | undefined
@@ -67,13 +70,14 @@ async function runPrefetch(args: PrefetchArgs): Promise<void> {
   // tells us which of the N stable hashes exist remotely, so we GET only the
   // hits and pre-mark the misses — their lazy `get` then short-circuits with
   // no network. This collapses N probe waves into 1 and skips every GET that
-  // would 404. When the remote can't batch (`null` — an older serve, or reads
-  // disabled), fall back to prefetching every stable key, exactly as before.
+  // would 404. When the remote can't batch (`null` — an older serve, 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 present = await args.cache.remoteHasMany(uniqueHashes)
+  const present = (await args.cache.remoteHasMany?.(uniqueHashes)) ?? null
   if (present !== null) {
-    args.cache.markRemoteAbsent(uniqueHashes.filter((h) => !present.has(h)))
+    args.cache.markRemoteAbsent?.(uniqueHashes.filter((h) => !present.has(h)))
     toPrefetch = stableKeys.filter((k) => present.has(k.hash))
     if (toPrefetch.length === 0) return
   }

package/src/orchestrator/resources.ts

@@ -1,39 +1,27 @@
-// Resolve `exec.resources` declarations into absolute per-task costs the
-// scheduler's 2-D admission gate packs against. Pure and budget-
-// parameterized — percent forms resolve here, ONCE per run, so the
-// scheduler's inner loop only ever does a Map.get. The loader has already
-// validated every form (this module trusts internal code); an
-// unparseable value can't reach it from a real config.
+// Resolve `exec.resources` declarations into the absolute per-task costs the
+// scheduler's 2-D admission gate packs against. Pure; the loader has already
+// validated every form (this module trusts internal code), so an unparseable
+// value can't reach it from a real config.
+//
+// The declared units are CPU CORES and MEGABYTES — the same numbers on this
+// machine and on a remote worker, which is why they are also what
+// `TaskPlacement.resources` hands an executor verbatim. Percent forms were
+// removed on 2026-08-30: a percentage names a fraction of THIS run's budget,
+// and an executor placing the task on someone else's machine has no way to
+// mean anything by it.
 
 import type { ResourceCost, TaskNode } from '../graph/index.js'
-import { parseSize } from '../util/index.js'
 
-const PERCENT_RE = /^(\d+(?:\.\d+)?)%$/
+const BYTES_PER_MB = 1024 * 1024
 
-/**
- * `cpus` → CPU units. A number is itself (fractional ok); `"<n>%"` is
- * percent of the CPU budget, kept fractional (rounding is display-only).
- * Absent → 0 = reserve nothing.
- */
-export function resolveCpu(v: number | string | undefined, cpuBudget: number): number {
-  if (v === undefined) return 0
-  if (typeof v === 'number') return v
-  const m = v.match(PERCENT_RE)
-  if (m) return (Number(m[1]) / 100) * cpuBudget
-  return 0
+/** `cpus` → CPU units. Absent → 0 = reserve nothing. */
+export function resolveCpu(v: number | undefined): number {
+  return v ?? 0
 }
 
-/**
- * `memory` → bytes. A number is bytes; a size string goes through
- * `parseSize` (`"2GB"`, `"512MB"`); `"<n>%"` is percent of the memory
- * budget. Absent → 0 = reserve nothing.
- */
-export function resolveMem(v: number | string | undefined, memBudget: number): number {
-  if (v === undefined) return 0
-  if (typeof v === 'number') return v
-  const m = v.match(PERCENT_RE)
-  if (m) return (Number(m[1]) / 100) * memBudget
-  return parseSize(v) ?? 0
+/** `memory` (megabytes) → bytes, which is what the budget axis counts. */
+export function resolveMem(v: number | undefined): number {
+  return v === undefined ? 0 : v * BYTES_PER_MB
 }
 
 /**
@@ -44,15 +32,13 @@ export function resolveMem(v: number | string | undefined, memBudget: number): n
  */
 export function resolveResourceCosts(
   nodes: ReadonlyMap<string, TaskNode>,
-  cpuBudget: number,
-  memBudget: number,
 ): Map<string, ResourceCost> {
   const out = new Map<string, ResourceCost>()
   for (const node of nodes.values()) {
     const declared = node.config.exec?.resources
     if (declared === undefined) continue
-    const cpu = resolveCpu(declared.cpus, cpuBudget)
-    const mem = resolveMem(declared.memory, memBudget)
+    const cpu = resolveCpu(declared.cpus)
+    const mem = resolveMem(declared.memory)
     if (cpu > 0 || mem > 0) out.set(node.id, { cpu, mem })
   }
   return out

package/src/orchestrator/run-artifacts.ts

@@ -14,7 +14,7 @@
 // Both are no-ops if the corresponding RunOptions field is undefined.
 
 import path from 'node:path'
-import type { TaskOutcome } from '../graph/index.js'
+import { isGroupTask, type TaskOutcome } from '../graph/index.js'
 import { tallyOutcomes } from './tally.js'
 
 export interface SummarizeArgs {
@@ -26,34 +26,59 @@ export interface SummarizeArgs {
   startedAtMs: number
   endedAtMs: number
   totalMs: number
+  /** The run's verdict — the same value the CLI turns into the exit code. */
+  ok: boolean
   outcomes: readonly TaskOutcome[]
 }
 
+/** One task's entry. Shared by `tasks` and `aborted` so they read alike. */
+function taskEntry(o: TaskOutcome): Record<string, unknown> {
+  return {
+    id: o.node.id,
+    project: o.node.projectName,
+    task: o.node.taskName,
+    status: o.status,
+    exitCode: o.exitCode,
+    durationMs: o.durationMs,
+    hash: o.hash ?? null,
+    ...(o.cpuMs !== undefined ? { cpuMs: o.cpuMs } : {}),
+    ...(o.peakRssBytes !== undefined ? { peakRssBytes: o.peakRssBytes } : {}),
+    // hrtime spans are bigints → emit as strings so JSON.parse on
+    // the consumer side doesn't truncate the ns precision.
+    ...(o.wallclockStartNs !== undefined ? { wallclockStartNs: String(o.wallclockStartNs) } : {}),
+    ...(o.wallclockEndNs !== undefined ? { wallclockEndNs: String(o.wallclockEndNs) } : {}),
+  }
+}
+
 export async function writeRunSummary(args: SummarizeArgs): Promise<string> {
   const outPath =
     args.target === ''
       ? path.join(args.cacheDir, 'runs', `${args.runId}.json`)
       : path.resolve(args.cwd, args.target)
+  // `tasks` and `summary` must describe the same population, or one artifact
+  // contradicts itself (a group task listed in `tasks` but absent from
+  // `summary.total`). `tallyOutcomes` owns the rule; mirror its filter here.
+  const counted = args.outcomes.filter((o) => !isGroupTask(o.node) && o.status !== 'aborted')
+  // A task killed by a shutdown signal is in no bucket and no total, yet it
+  // makes the run red. Listing it separately keeps `tasks.length ===
+  // summary.total` while leaving the artifact able to explain a non-zero
+  // exit — the terminal has said so in its Aborted section all along, and a
+  // parser must not be told less than a human is.
+  const aborted = args.outcomes.filter((o) => !isGroupTask(o.node) && o.status === 'aborted')
   const payload = {
     runId: args.runId,
+    // The run-level verdict, first: a consumer gating on this artifact must
+    // not have to re-derive it by re-implementing the bucket rules.
+    ok: args.ok,
+    exitCode: args.ok ? 0 : 1,
     startedAt: new Date(args.startedAtMs).toISOString(),
     endedAt: new Date(args.endedAtMs).toISOString(),
     totalMs: args.totalMs,
-    tasks: args.outcomes.map((o) => ({
-      id: o.node.id,
-      project: o.node.projectName,
-      task: o.node.taskName,
-      status: o.status,
-      exitCode: o.exitCode,
-      durationMs: o.durationMs,
-      hash: o.hash ?? null,
-      ...(o.cpuMs !== undefined ? { cpuMs: o.cpuMs } : {}),
-      ...(o.peakRssBytes !== undefined ? { peakRssBytes: o.peakRssBytes } : {}),
-      // hrtime spans are bigints → emit as strings so JSON.parse on
-      // the consumer side doesn't truncate the ns precision.
-      ...(o.wallclockStartNs !== undefined ? { wallclockStartNs: String(o.wallclockStartNs) } : {}),
-      ...(o.wallclockEndNs !== undefined ? { wallclockEndNs: String(o.wallclockEndNs) } : {}),
-    })),
+    tasks: counted.map(taskEntry),
+    aborted: aborted.map(taskEntry),
+    // The FULL list: `tallyOutcomes` applies the same group/aborted
+    // exclusions internally, so every counted bucket is unchanged by passing
+    // it — but `summary.aborted` is only non-zero if it sees them.
     summary: tallyOutcomes(args.outcomes),
   }
   await Bun.write(outPath, JSON.stringify(payload, null, 2))