@vzn/vx 0.0.18 → 0.0.22

package/src/orchestrator/plugin-host.ts

@@ -1,20 +1,22 @@
 // Plugin consultation for the run-level extension points (cache / executor).
-// Each function asks the plugins in order. Nothing is applied by default:
-// core's own executor and cache are plugins under src/plugins/ that a
-// workspace declares like any other, so a list with no provider for a
-// load-bearing capability fails fast with MISSING_PLUGIN_HINT.
+// Each function asks the plugins in order, and CORE IS THE TAIL: running
+// here and caching here are what those words mean in the absence of a
+// plugin placing work elsewhere or storing it somewhere else. A plugin
+// goes in front — it takes what it accepts, and what it declines lands on
+// the floor. No plugin is required for a plain local run.
 //
-// See docs/design/core-cloud-split-2026-06.md §5.1.
+// See docs/design/pipeline-2026-09.md.
 
 import { ChainedCache, type CacheLayer } from '../cache/index.js'
-import type { TaskExecutor } from '../exec/index.js'
+import { localExecutor, type TaskExecutor } from '../exec/index.js'
 import { settleWithin, teardownTimeoutMs, UserError } from '../util/index.js'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
-import { detectCycle, type TaskNode } from '../graph/index.js'
-import { MISSING_PLUGIN_HINT } from './missing-plugin.js'
+import { checkGraph, type TaskNode } from '../graph/index.js'
 import type {
   CacheContext,
   ExecutorContext,
+  FingerprintChange,
+  FingerprintContext,
   GraphHookContext,
   KeyHookContext,
   ProjectHookContext,
@@ -23,12 +25,58 @@ import type {
   WorkspaceHookContext,
 } from './plugin.js'
 
+/** `a string`, `an array`, `null`, `a number` — for a refusal that names what came back. */
+function describeValue(v: unknown): string {
+  if (v === null) return 'null'
+  if (Array.isArray(v)) return 'an array'
+  const t = typeof v
+  return t === 'object' ? 'an object' : `a ${t}`
+}
+
+/** Every method `CacheLayer` requires (the optional ones are probed with `?.`). */
+export const CACHE_LAYER_METHODS: readonly string[] = [
+  'key',
+  'get',
+  'has',
+  'prefetch',
+  'loadOutputFilesBatch',
+  'isOutputsCurrent',
+  'restoreOutputs',
+  'save',
+  'ingest',
+  'recordRunBundle',
+  'stats',
+  'hashFile',
+  'outputsPath',
+  'prune',
+  'close',
+]
+
+/** What a capability hook handed back must be what the seam runs. */
+function assertShape(
+  plugin: VxPlugin,
+  hook: string,
+  value: unknown,
+  methods: readonly string[],
+  what: string,
+): void {
+  const missing =
+    value === null || typeof value !== 'object'
+      ? methods
+      : methods.filter((m) => typeof (value as Record<string, unknown>)[m] !== 'function')
+  if (missing.length === 0) return
+  throw new UserError(
+    `plugin '${plugin.name}' returned from ${hook} something that is not ${what}: ` +
+      `missing ${missing.map((m) => `${m}()`).join(', ')}`,
+  )
+}
+
 /**
  * Run a capability factory with crash isolation. A throw becomes a clean
- * `UserError` naming the plugin + hook for the load-bearing capabilities
- * (`cache`/`executor`/`setup`) — a broken cache or executor must abort with
- * a clear message, never silently degrade. For `eventSink` the caller
- * logs-and-skips instead (observability must never break a run).
+ * `UserError` naming the plugin + hook: every stage and capability resolved
+ * here is load-bearing, so a broken one must abort with a clear message,
+ * never silently degrade. (Telemetry sinks are the observe-only exception,
+ * and telemetry-host.ts logs-and-skips them instead.)
  */
 async function safe<T>(plugin: VxPlugin, hook: string, fn: () => T | Promise<T>): Promise<T> {
   try {
@@ -49,7 +97,7 @@ async function safe<T>(plugin: VxPlugin, hook: string, fn: () => T | Promise<T>)
 
 export function hasHook(
   plugins: readonly VxPlugin[],
-  hook: 'config' | 'project' | 'graph' | 'key' | 'schedule',
+  hook: 'config' | 'project' | 'graph' | 'key' | 'schedule' | 'admit',
 ): boolean {
   for (const p of plugins) if (p[hook] !== undefined) return true
   return false
@@ -72,18 +120,24 @@ export async function applyProjectHooks(
   plugins: readonly VxPlugin[],
   config: ProjectConfig,
   ctx: ProjectHookContext,
+  /** Runs after EACH plugin's edit, so a refusal can name the plugin that made it. */
+  afterEach?: (plugin: VxPlugin) => void,
 ): Promise<void> {
   for (const plugin of plugins) {
     if (plugin.project === undefined) continue
     await safe(plugin, 'project', () => plugin.project!(config, ctx))
+    afterEach?.(plugin)
   }
 }
 
 /**
  * `graph` stage: every plugin edits the task graph in place, then the graph
- * is checked the way the builder checks its own output — every dep names a
- * node in the graph, and there is no cycle. A violation is reported against
- * the LAST plugin that ran, which is the one whose edit made it so.
+ * is checked ONCE the way the builder checks its own output (`checkGraph`:
+ * each node under its own id, every dep a node, no cycle, no two tasks
+ * deleting each other's outputs). A violation is reported
+ * against the LAST plugin that ran: usually the one whose edit made it so,
+ * but an earlier plugin's edit that a later one left in place is blamed on
+ * the later one, since nothing is checked between plugins.
  */
 export async function applyGraphHooks(
   plugins: readonly VxPlugin[],
@@ -97,16 +151,7 @@ export async function applyGraphHooks(
     last = plugin
   }
   if (last === undefined) return
-  await safe(last, 'graph', () => {
-    for (const node of nodes.values()) {
-      for (const dep of node.deps) {
-        if (!nodes.has(dep)) {
-          throw new Error(`${node.id} depends on '${dep}', which is not a task in this run's graph`)
-        }
-      }
-    }
-    detectCycle(nodes)
-  })
+  await safe(last, 'graph', () => checkGraph(nodes))
 }
 
 /**
@@ -125,6 +170,14 @@ export async function applyKeyHooks(
       if (plugin.key === undefined) continue
       const material = await safe(plugin, 'key', () => plugin.key!(node, ctx))
       if (material === undefined) continue
+      // `Object.entries` over a string yields its characters as string
+      // values, so a plugin returning `'v22'` used to fold parts named
+      // '0', '1', '2' into every key — silently, and permanently.
+      if (typeof material !== 'object' || material === null || Array.isArray(material)) {
+        throw new UserError(
+          `plugin '${plugin.name}' failed in key: returned ${describeValue(material)}, not a record of string values`,
+        )
+      }
       for (const [name, value] of Object.entries(material)) {
         if (typeof value !== 'string') {
           throw new UserError(
@@ -141,6 +194,50 @@ export async function applyKeyHooks(
   }
 }
 
+/**
+ * The fingerprint files the plugins claim (`VxPlugin.fingerprint`), each
+ * with its one claimant. The schema refused a second claimant and an
+ * unknown name, so this only indexes.
+ */
+export function fingerprintClaims(plugins: readonly VxPlugin[]): ReadonlyMap<string, VxPlugin> {
+  const claims = new Map<string, VxPlugin>()
+  for (const p of plugins) {
+    if (p.fingerprint === undefined) continue
+    for (const f of p.fingerprint.files) claims.set(f, p)
+  }
+  return claims
+}
+
+/**
+ * Ask a claimed file's plugin which projects a change to it affects.
+ * `undefined` is "every project" — the claimant could not tell — and a
+ * non-iterable answer is refused by name, so a plugin returning `'all'`
+ * cannot select the projects spelled a, l, l.
+ */
+export async function claimedAffected(
+  plugin: VxPlugin,
+  change: FingerprintChange,
+  ctx: FingerprintContext,
+): Promise<Set<string> | undefined> {
+  const answer = await safe(plugin, 'fingerprint', () => plugin.fingerprint!.affected(change, ctx))
+  if (answer === undefined) return undefined
+  if (typeof answer === 'string' || typeof answer !== 'object' || answer === null) {
+    throw new UserError(
+      `plugin '${plugin.name}' failed in fingerprint: returned ${describeValue(answer)}, not a list of project names`,
+    )
+  }
+  const names = new Set<string>()
+  for (const name of answer as Iterable<unknown>) {
+    if (typeof name !== 'string') {
+      throw new UserError(
+        `plugin '${plugin.name}' failed in fingerprint: affected project ${describeValue(name)} is not a name`,
+      )
+    }
+    names.add(name)
+  }
+  return names
+}
+
 /**
  * `schedule` stage: the merged priorities map (a later plugin's weight for
  * a task overrides an earlier one's). Empty when no plugin answered.
@@ -155,6 +252,14 @@ export async function applyScheduleHooks(
     if (plugin.schedule === undefined) continue
     const weights = await safe(plugin, 'schedule', () => plugin.schedule!(nodes, ctx))
     if (weights === undefined) continue
+    // Iterating a string destructures its characters into `[id, w]` pairs
+    // that match no task — a plugin returning `'fast'` used to be a no-op
+    // with no word said.
+    if (!(weights instanceof Map)) {
+      throw new UserError(
+        `plugin '${plugin.name}' failed in schedule: returned ${describeValue(weights)}, not a Map of task id → weight`,
+      )
+    }
     for (const [id, w] of weights) {
       if (!nodes.has(id)) continue
       if (typeof w !== 'number' || !Number.isFinite(w)) {
@@ -168,13 +273,53 @@ export async function applyScheduleHooks(
   return merged
 }
 
+/**
+ * `admit` stage, built once per run into the predicate the scheduler asks
+ * at every local dispatch: every plugin that answers must admit. A plugin
+ * that throws is reported once and admits from then on — a policy never
+ * breaks a run — so the predicate is never the reason a task hangs.
+ * Undefined when no plugin answers, which keeps the scheduler on its
+ * count-only path.
+ */
+export function buildAdmission(
+  plugins: readonly VxPlugin[],
+  nodes: ReadonlyMap<string, TaskNode>,
+  concurrency: number,
+  warn: (message: string) => void,
+): ((id: string, running: ReadonlySet<string>) => boolean) | undefined {
+  const answering = plugins.filter((p) => p.admit !== undefined)
+  if (answering.length === 0) return undefined
+  const broken = new Set<VxPlugin>()
+  return (id, running) => {
+    // The scheduler asks only about ids in this same map, so the lookup
+    // always lands: an unknown-id arm here was deleted with the whole core
+    // suite green (item 651).
+    const task = nodes.get(id)!
+    const ctx = {
+      running: [...running].flatMap((r) => nodes.get(r) ?? []),
+      concurrency,
+    }
+    for (const plugin of answering) {
+      if (broken.has(plugin)) continue
+      try {
+        if (plugin.admit!(task, ctx) === false) return false
+      } catch (err) {
+        broken.add(plugin)
+        const m = err instanceof Error ? err.message : String(err)
+        warn(`plugin '${plugin.name}' failed in admit: ${m}; admitting every task from here on`)
+      }
+    }
+    return true
+  }
+}
+
 /**
  * Collect every plugin's `cache` layer in declaration order. One layer is
  * used as is; two or more are chained (lookup walks them, save reaches all;
  * see ChainedCache). A bare local layer that another declared layer already
  * wraps (`layer.local === ctx.localCache`) is dropped, so a remote plugin
- * that layers over the local handle composes with `localCachePlugin()`
- * instead of writing the local store twice. No layer at all is a named error.
+ * that layers over the local handle does not also write the local store
+ * directly. A plugin declaring nothing leaves that store, unwrapped.
  */
 export async function resolveCache(
   plugins: readonly VxPlugin[],
@@ -184,25 +329,30 @@ export async function resolveCache(
   for (const plugin of plugins) {
     if (plugin.cache === undefined) continue
     const layer = await safe(plugin, 'cache', () => plugin.cache!(ctx))
-    if (layer !== undefined) layers.push(layer)
-  }
-  if (layers.length === 0) {
-    const declined = plugins.filter((p) => p.cache !== undefined).map((p) => `${p.name} declined`)
-    throw new UserError(
-      `no cache plugin declared${declined.length > 0 ? ` (${declined.join(', ')})` : ''}. ${MISSING_PLUGIN_HINT}`,
-    )
+    if (layer === undefined) continue
+    // The seam's WHOLE contract, checked once here: a layer missing a
+    // method otherwise failed at the first task that reached it — an
+    // internal TypeError deep in the chain, naming neither the plugin nor
+    // the hook. Five names were checked before, so a layer with those five
+    // passed and died at its first hit inside restoreOutputs.
+    assertShape(plugin, 'cache', layer, CACHE_LAYER_METHODS, 'a cache layer')
+    layers.push(layer)
   }
+  // Core's own store is the TAIL of the chain — the floor under every
+  // lookup, not a plugin a workspace has to declare. A layer that WRAPS
+  // the local handle subsumes it below, so a remote plugin does not write
+  // the local store twice.
+  if (!layers.includes(ctx.localCache)) layers.push(ctx.localCache)
   const wrapsLocal = layers.some((l) => l !== ctx.localCache && l.local === ctx.localCache)
   const distinct = wrapsLocal ? layers.filter((l) => l !== ctx.localCache) : layers
   return distinct.length === 1 ? distinct[0]! : new ChainedCache(distinct)
 }
 
 /**
- * Collect every plugin's `executor`, in declaration order. Unlike
- * `cache` this is a LIST: per task, `selectExecutor` takes the first
- * that accepts. An empty list is the same authoring error as a missing
- * cache provider and fails the same way. A broken factory aborts — an
- * executor is load-bearing, not observational.
+ * Collect every plugin's `executor`, in declaration order, with core's
+ * own appended at the tail: per task, `selectExecutor` takes the first
+ * that accepts, and what every plugin declines runs here. A broken
+ * factory aborts — an executor is load-bearing, not observational.
  */
 export async function resolveExecutors(
   plugins: readonly VxPlugin[],
@@ -212,16 +362,17 @@ export async function resolveExecutors(
   for (const plugin of plugins) {
     if (plugin.executor === undefined) continue
     const executor = await safe(plugin, 'executor', () => plugin.executor!(ctx))
-    if (executor !== undefined) executors.push(executor)
-  }
-  if (executors.length === 0) {
-    const declined = plugins
-      .filter((p) => p.executor !== undefined)
-      .map((p) => `${p.name} declined`)
-    throw new UserError(
-      `no executor plugin declared${declined.length > 0 ? ` (${declined.join(', ')})` : ''}. ${MISSING_PLUGIN_HINT}`,
-    )
+    if (executor === undefined) continue
+    assertShape(plugin, 'executor', executor, ['execute'], 'an executor')
+    if (typeof executor.name !== 'string' || executor.name.length === 0) {
+      throw new UserError(`plugin '${plugin.name}' returned an executor with no name`)
+    }
+    executors.push(executor)
   }
+  // Core's own executor is the TAIL of every list, so a plugin executor
+  // that declines a task hands it back to this machine rather than
+  // failing the run.
+  executors.push(localExecutor())
   return executors
 }
 

package/src/orchestrator/plugin.ts

@@ -8,11 +8,15 @@
 // run with a clean UserError naming plugin + hook. A plugin that throws
 // inside a bus hook is logged and disabled for the remainder of the run.
 
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import type { Cache, CacheLayer, CachePolicy } from '../cache/index.js'
-import type { ProjectConfig, WorkspaceConfig } from '../config.js'
+import { PLUGIN_PACKAGE, type ProjectConfig, type WorkspaceConfig } from '../config.js'
 import type { TaskExecutor } from '../exec/index.js'
 import type { TaskNode, TaskOutcome } from '../graph/index.js'
 import { UserError } from '../util/index.js'
+import type { ProjectMeta } from '../workspace/index.js'
 import type { EventBus, RunStartInfo } from './events.js'
 import type { TelemetryContext, TelemetrySink } from './telemetry.js'
 
@@ -32,7 +36,12 @@ import type { TelemetryContext, TelemetrySink } from './telemetry.js'
  * outside the list.
  */
 export interface VxPlugin {
-  /** Stable identifier, convention `'org/name'`. Used in errors + precedence logs. */
+  /**
+   * The name of the package the plugin was defined in — set by
+   * `definePlugin` from the nearest `package.json`, never by the plugin.
+   * Heads every warning about the plugin, every `vx info` line, and the
+   * key material a `key` hook contributes.
+   */
   readonly name: string
 
   // --- PIPELINE stages (shape the run before it executes — opt-in) ----------
@@ -54,7 +63,10 @@ export interface VxPlugin {
    * One project's validated config, right after it loaded and before the
    * graph is built. Add, remove or edit tasks. Runs for every loaded project
    * on every run — a config's cached evaluation is the user's file, and the
-   * hook is applied on top of it live.
+   * hook is applied on top of it live. A package with NO config file is
+   * loaded too, as `{ tasks: {} }`, so a plugin can give tasks to packages
+   * that never wrote one (`ctx.packageJson` carries their scripts); with no
+   * `project` plugin such a package is never visited.
    */
   project?(config: ProjectConfig, ctx: ProjectHookContext): void | Promise<void>
 
@@ -82,6 +94,26 @@ export interface VxPlugin {
     | undefined
     | Promise<Readonly<Record<string, string>> | undefined>
 
+  /**
+   * Workspace-root files this plugin keys on its own, taken OUT of the
+   * workspace fingerprint. Core folds every lockfile it knows into every
+   * task's key, so one `pnpm install` re-keys the whole workspace. A plugin
+   * that reads the lockfile and folds each project's own dependency
+   * closure through `key` claims the file here: core leaves it out of the
+   * fingerprint every key sees (the config-evaluation cache still keys on
+   * it — a config may import a dependency), and `--affected` asks
+   * `affected` which projects a change to it touches instead of selecting
+   * every project. A file has one claimant.
+   *
+   * A root file core does NOT fold is claimed the same way when the
+   * plugin's stages read it: `turbo()` shapes every task from
+   * `turbo.json`, so an edit to it re-keys tasks through their resolved
+   * configs while no project owns the path. Nothing is taken out;
+   * `--affected` asks `affected` (undefined: every project) and `vx watch`
+   * re-runs on an edit (item 961). A claim is a bare name at the root.
+   */
+  readonly fingerprint?: FingerprintClaim
+
   /**
    * Scheduling priorities: task id → weight, higher runs first among READY
    * tasks (merged over the structural baseline, which stays the tie-break).
@@ -93,6 +125,20 @@ export interface VxPlugin {
     ctx: ScheduleHookContext,
   ): ReadonlyMap<string, number> | undefined | Promise<ReadonlyMap<string, number> | undefined>
 
+  /**
+   * Admission over the worker count: asked for every task about to start
+   * on this machine, with the tasks running here right now. Return `false`
+   * to hold it until something finishes (it is asked again then). Asked
+   * many times per run, so it must be cheap and synchronous; a throw is
+   * reported once and the plugin admits from then on — a policy never
+   * breaks a run. Restore-tier hits and tasks on an executor pool hold no
+   * local resources and are never asked. When several plugins answer, all
+   * must admit. Core keeps no notion of what a task needs: a plugin that
+   * packs memory or CPU learns or declares the numbers itself
+   * (`@vzn/vx-schedule-history` packs what past executions used).
+   */
+  admit?(task: TaskNode, ctx: AdmitContext): boolean
+
   // --- CLI verbs (opt-in) ---------------------------------------------------
 
   /**
@@ -110,8 +156,9 @@ export interface VxPlugin {
    * Contribute a cache layer. Returns a CacheLayer wrapping (or replacing)
    * the local Cache, or undefined to decline. Consulted ONCE per prepareRun.
    * Precedence: first non-undefined plugin cache wins, in declaration
-   * order. `@vzn/vx/plugins/local-cache` hands back the bare local Cache;
-   * a list with no provider fails the run before any task starts.
+   * order, ahead of core's own `.vx/cache` handle at the tail. A layer
+   * that WRAPS the local handle subsumes that tail, so it is not written
+   * twice.
    */
   cache?(ctx: CacheContext): CacheLayer | undefined | Promise<CacheLayer | undefined>
 
@@ -119,10 +166,10 @@ export interface VxPlugin {
    * Contribute a task executor — WHERE one task's command runs. Consulted
    * ONCE per run; every contributed executor is kept, in declaration order,
    * and per task the first whose `accepts()` passes executes it. Nothing is
-   * appended: a workspace declares `localExecutorPlugin()` (from
-   * `@vzn/vx/plugins/local-executor`) like any other, and a run with no
-   * executor at all fails before any task runs. Persistent tasks never
-   * reach an executor (local by construction).
+   * appended in front: core's own local executor is always the TAIL, so
+   * declining a task hands it back to this machine rather than failing
+   * the run. Persistent tasks never reach an executor (local by
+   * construction).
    */
   executor?(ctx: ExecutorContext): TaskExecutor | undefined | Promise<TaskExecutor | undefined>
 
@@ -146,9 +193,13 @@ export interface VxPlugin {
     | Promise<TelemetrySink | TelemetrySink[] | undefined>
 
   /**
-   * Optional one-time setup before any capability is consulted (validate the
-   * workspace, open a connection, read a token). Throwing aborts the run with
-   * a clean UserError naming the plugin — same contract as the old setup().
+   * Optional one-time setup per run (validate the workspace, open a
+   * connection, read a token). Throwing aborts the run with a clean
+   * UserError naming the plugin. It is not a guard over the pipeline: the
+   * config, project, cache, graph, key and schedule stages have run by the
+   * time it is called, and a plan (`--dry`, `planRun`) never calls it. It
+   * precedes the executors, the telemetry sinks, admission and the first
+   * task (tests/plugin-e2e.test.ts).
    */
   setup?(ctx: PluginSetupContext): void | Promise<void>
 
@@ -188,6 +239,18 @@ export interface ProjectHookContext extends BaseContext {
   readonly dir: string
   /** The parsed `package.json`, read-only. */
   readonly packageJson: Readonly<Record<string, unknown>>
+  /**
+   * Every package the workspace discovered — the one being visited, the
+   * rest of the run's scope and the packages outside it, config file or
+   * not — as core read them at startup. A plugin whose mapping needs the
+   * whole workspace (a `dependsOn` is only valid against every package's
+   * scripts at once) reads it here instead of walking the workspace a
+   * second time. The same array is handed to every visit of a run and a
+   * new one to the next run — a plugin instance outlives a run under `vx
+   * watch`, so a per-run memo keys on this array's identity, never on the
+   * process.
+   */
+  readonly projects: readonly ProjectMeta[]
 }
 
 export interface GraphHookContext extends BaseContext {
@@ -197,6 +260,42 @@ export interface GraphHookContext extends BaseContext {
 
 export interface KeyHookContext extends BaseContext {}
 
+/** A plugin's claim on workspace fingerprint files — see `VxPlugin.fingerprint`. */
+export interface FingerprintClaim {
+  /** Bare names at the workspace root: a lockfile core folds (`pnpm-lock.yaml`) or a file the plugin reads (`turbo.json`). */
+  readonly files: readonly string[]
+  /**
+   * The projects (package names) a change to a claimed file affects. Called
+   * by `--affected` with the file's bytes at the base ref and in the
+   * working tree (`null` where it does not exist). Return `undefined` to
+   * select every project — the answer a claimant gives when it cannot
+   * tell, and what core does for an unclaimed file.
+   */
+  affected(
+    change: FingerprintChange,
+    ctx: FingerprintContext,
+  ): Iterable<string> | undefined | Promise<Iterable<string> | undefined>
+}
+
+export interface FingerprintChange {
+  /** The claimed file's root-relative name. */
+  readonly file: string
+  readonly before: Uint8Array | null
+  readonly after: Uint8Array | null
+}
+
+export interface FingerprintContext extends BaseContext {
+  /** Every project in the workspace: package name and absolute directory. */
+  readonly projects: ReadonlyArray<{ readonly name: string; readonly dir: string }>
+}
+
+export interface AdmitContext {
+  /** The tasks executing on this machine right now, in dispatch order. */
+  readonly running: readonly TaskNode[]
+  /** The run's worker count — the ceiling the count gate already applies. */
+  readonly concurrency: number
+}
+
 export interface ScheduleHookContext extends BaseContext {
   /** The run's local cache handle — its `dbHandle()` holds the run history a policy can learn from. */
   readonly localCache: Cache
@@ -219,7 +318,10 @@ export interface PluginContext {
   readonly workspaceRoot: string
   /** Where vx's cache lives — read-only as far as the plugin is concerned. */
   readonly cacheDir: string
-  /** The run event bus. A plugin can subscribe directly if its needs exceed the hooks. */
+  /**
+   * The run event bus. A plugin can subscribe directly if its needs exceed
+   * the hooks; the subscription ends with the run, as a hook's does.
+   */
   readonly bus: EventBus
   /**
    * Convenience: register a typed handler keyed off `RunEvent.kind`.
@@ -263,6 +365,70 @@ export interface Plugin {
   setup?(ctx: PluginContext): void | Promise<void>
 }
 
+/** What a plugin author writes: every hook, and no name. */
+export type PluginHooks = Omit<VxPlugin, 'name'>
+
+/**
+ * Where a plugin is defined — `import.meta` of its module. `dir` is Bun's
+ * field; `url` is the standard one, for a module evaluated elsewhere.
+ */
+export interface PluginOrigin {
+  readonly dir?: string
+  readonly url?: string
+}
+
+const packageNameByDir = new Map<string, string>()
+
+/** The name of the nearest `package.json` above `dir` — the one that owns it. */
+function pluginPackageName(dir: string): string {
+  const memo = packageNameByDir.get(dir)
+  if (memo !== undefined) return memo
+  for (let d = dir; ;) {
+    let text: string | undefined
+    try {
+      text = readFileSync(path.join(d, 'package.json'), 'utf8')
+    } catch {
+      /* not here; look one level up */
+    }
+    if (text !== undefined) {
+      const name = (JSON.parse(text) as { name?: unknown }).name
+      if (typeof name !== 'string' || name.length === 0) {
+        throw new UserError(
+          `definePlugin: ${path.join(d, 'package.json')} has no name — a plugin is a package, and its name is the package's`,
+        )
+      }
+      packageNameByDir.set(dir, name)
+      return name
+    }
+    const parent = path.dirname(d)
+    if (parent === d) {
+      throw new UserError(
+        `definePlugin: no package.json above ${dir} — a plugin is a package, and its name is the package's`,
+      )
+    }
+    d = parent
+  }
+}
+
+/**
+ * The one way to make a plugin: `definePlugin(import.meta, { ...hooks })`.
+ * The name is read from the package the calling module belongs to — the
+ * nearest `package.json` above it — and stamped where the workspace loader
+ * checks for it, so a plugin cannot be named anything but its package.
+ */
+export function definePlugin(origin: PluginOrigin, hooks: PluginHooks): VxPlugin {
+  if ('name' in hooks) {
+    throw new UserError(`definePlugin: a plugin's name is its package name — drop the 'name' field`)
+  }
+  const dir =
+    origin.dir ?? (origin.url !== undefined ? path.dirname(fileURLToPath(origin.url)) : undefined)
+  if (dir === undefined) {
+    throw new UserError(`definePlugin: the first argument must be the plugin module's import.meta`)
+  }
+  const name = pluginPackageName(dir)
+  return { ...hooks, name, [PLUGIN_PACKAGE]: name } as VxPlugin
+}
+
 export interface InstallPluginsArgs {
   plugins: readonly Plugin[]
   workspaceRoot: string
@@ -307,7 +473,17 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
     const ctx: PluginContext = {
       workspaceRoot,
       cacheDir,
-      bus,
+      // A subscription made past the hooks leaves with the run like a
+      // hook's does: the bus can outlive the run (`RunOptions.bus`), and
+      // one left behind hears every later run on it (item 635).
+      bus: {
+        emit: (event) => bus.emit(event),
+        subscribe(subscriber) {
+          const dispose = bus.subscribe(subscriber)
+          disposers.push(dispose)
+          return dispose
+        },
+      },
       on(hook, handler) {
         const dispose = bus.subscribe((event) => {
           if (disabled.has(plugin.name)) return