@vzn/vx 0.0.652 → 0.0.653

package/src/orchestrator/plugin.ts

@@ -31,7 +31,9 @@ import {
 } from '../util/index.js'
 import * as ui from '../ui/index.js'
 import type { ProjectMeta } from '../workspace/index.js'
-import type { EventBus, Logger, RunStartInfo } from '../report/index.js'
+import type { EventBus, Logger, RunEvent, RunStartInfo } from '../report/index.js'
+import { readOnlyEvents } from './read-only.js'
+import { unlessStopped } from './signals.js'
 import type { CiContext } from './run-context.js'
 import type { CacheFacts, TaskArtifacts } from './task-artifacts.js'
 import type { TelemetryContext, TelemetrySink } from './telemetry.js'
@@ -121,7 +123,7 @@ export interface VxPlugin {
    * feature flag, anything the declared inputs cannot see. Runs once per
    * task per run, before any key is derived. Return undefined to add
    * nothing. Values must be deterministic for the same inputs or the key
-   * never hits.
+   * never hits. The task is read-only (a write throws): `graph` edits tasks.
    */
   key?(
     task: TaskNode,
@@ -153,6 +155,7 @@ export interface VxPlugin {
    * The run waits for this answer before its first task, so it should
    * come from what is at hand (local history); better weights that need
    * a fetch go to `ctx.refine` when they arrive, without holding the run.
+   * The nodes are read-only (a write throws): their keys are taken.
    */
   schedule?(
     nodes: ReadonlyMap<string, TaskNode>,
@@ -170,7 +173,8 @@ export interface VxPlugin {
    * hold no local resources: never asked, never in `ctx.running`. 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-history` packs what past executions used).
+   * (`@vzn/vx-history` packs what past executions used). The task and
+   * `ctx.running` are read-only (a write throws, and admits from then on).
    */
   admit?(task: TaskNode, ctx: AdmitContext): boolean
 
@@ -234,9 +238,10 @@ export interface VxPlugin {
    * renderer in place. The first plugin, in declaration order, that
    * returns one renders the run; the rest are not asked. Not consulted
    * when an embedder passed its own `log`. A logger that throws or rejects
-   * hands the rest of the run back to core's renderer with one warning; a
-   * hook that does not answer within the teardown bound (3 s) is passed
-   * over with one.
+   * hands the rest of the run back to core's renderer with one warning, and
+   * core draws the event it was handed; a hook that does not answer within
+   * the teardown bound (3 s) is passed over with one. The nodes and
+   * outcomes it is handed are read-only: a write throws.
    */
   output?(ctx: OutputContext): Logger | undefined | Promise<Logger | undefined>
 
@@ -268,7 +273,8 @@ export interface VxPlugin {
  * task that saved no entry, and a failed task's log and the files its
  * outputs left when `cache.upload.failures` covers the run. Read
  * them with `ctx.cache.getRun(name)`. Core keeps no manifest of its own; a
- * plugin that wants one writes it from here (`ctx.cache.put`).
+ * plugin that wants one writes it from here (`ctx.cache.put`). Frozen:
+ * every teardown reads the same report.
  */
 export interface RunReport {
   /** The `run_id` the run's history rows and telemetry carry. */
@@ -317,6 +323,8 @@ export interface PluginSetupContext extends BaseContext, PluginSecrets {
   /**
    * Subscribe a lifecycle handler; it leaves with the run. A throw or a
    * rejection warns once and switches the plugin's handlers off for the run.
+   * What a handler is handed is read-only: a write throws, so a handler
+   * can never turn a failed task into a pass.
    */
   on<K extends PluginHookName>(hook: K, handler: PluginHookHandlers[K]): void
 }
@@ -397,7 +405,11 @@ export interface ConfigContext extends WorkspaceHookContext {
 export interface DiscoverContext extends WorkspaceHookContext {
   /** Where vx's cache lives: a plugin may keep what it read to answer here. */
   readonly cacheDir: string
-  /** The projects found so far: the lock's, then earlier plugins'. */
+  /**
+   * The projects found so far: the lock's, then earlier plugins'. Read-only,
+   * entries too (a write throws): a project is added by returning it. The
+   * same object `project` hooks get as `ctx.projects`.
+   */
   readonly projects: readonly ProjectMeta[]
   /**
    * What `git status` lists in the workspace, workspace-relative: modified,
@@ -436,10 +448,11 @@ export interface ProjectHookContext extends BaseContext {
    * not — as the `discover` stage left them. 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
+   * second time. The same array (`discover`'s) 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.
+   * process. Frozen, entries too: a hook edits its own project's config,
+   * never which projects there are or where they live.
    */
   readonly projects: readonly ProjectMeta[]
   /**
@@ -656,7 +669,8 @@ export interface ExecutorContext extends BaseContext {
 export interface PluginContext extends PluginSetupContext {
   /**
    * 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.
+   * the hooks; the subscription ends with the run, as a hook's does. The
+   * events a subscriber gets are read-only, as a hook's are.
    */
   readonly bus: EventBus
 }
@@ -670,16 +684,16 @@ export type PluginHookName =
   | 'onRunStatus'
   | 'onRunEnd'
 
-// A Record so the compiler holds it to `PluginHookName` both ways: a name
-// missing here, or one the type lacks, does not compile.
-const HOOK_NAMES: Record<PluginHookName, true> = {
-  onRunStart: true,
-  onTaskStart: true,
-  onTaskStdout: true,
-  onTaskStderr: true,
-  onTaskComplete: true,
-  onRunStatus: true,
-  onRunEnd: true,
+// Each hook's event. A Record so the compiler holds it to `PluginHookName`
+// both ways: a name missing here, or one the type lacks, does not compile.
+const HOOK_EVENTS: Record<PluginHookName, RunEvent['kind']> = {
+  onRunStart: 'run:start',
+  onTaskStart: 'task:start',
+  onTaskStdout: 'task:stdout',
+  onTaskStderr: 'task:stderr',
+  onTaskComplete: 'task:complete',
+  onRunStatus: 'run:status',
+  onRunEnd: 'run:end',
 }
 
 export interface PluginHookHandlers {
@@ -898,6 +912,8 @@ export interface InstallPluginsArgs {
   secrets?: SecretBroker
   /** Each setup as the step `<plugin>:setup`; default: untimed. */
   step?: <T>(id: string, work: () => Promise<T>) => Promise<T>
+  /** The run's held signals: a stop ends a setup's wait, which then throws. */
+  signal?: AbortSignal | undefined
 }
 
 /**
@@ -932,6 +948,9 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
   const disposers: Array<() => void> = []
   // By object, not name: one package can export two plugins.
   const disabled = new Set<Plugin>()
+  // Made at the first event a plugin hears: a run no handler hears pays nothing.
+  let readOnly: ((event: RunEvent) => RunEvent) | undefined
+  const viewOf = (event: RunEvent): RunEvent => (readOnly ??= readOnlyEvents())(event)
 
   for (const plugin of plugins) {
     if (typeof plugin.name !== 'string' || plugin.name.length === 0) {
@@ -976,7 +995,7 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
             if (disabled.has(plugin)) return
             let ret: unknown
             try {
-              ret = subscriber(event)
+              ret = subscriber(viewOf(event))
             } catch (err) {
               fail('a bus subscriber', err)
               return
@@ -990,9 +1009,9 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
       on(hook, handler) {
         // A misspelt name ('taskComplete') subscribed a handler that never
         // ran, and no word of it; a config file has no type-checker (H-16).
-        if (!Object.hasOwn(HOOK_NAMES, hook)) {
+        if (!Object.hasOwn(HOOK_EVENTS, hook)) {
           throw new Error(
-            `ctx.on: unknown hook '${String(hook)}' (one of ${Object.keys(HOOK_NAMES).join(', ')})`,
+            `ctx.on: unknown hook '${String(hook)}' (one of ${Object.keys(HOOK_EVENTS).join(', ')})`,
           )
         }
         // Taken, it threw at the first event and switched the whole plugin off.
@@ -1002,8 +1021,9 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
           )
         }
         const onFail = (err: unknown): void => fail(hook, err)
-        const dispose = bus.subscribe((event) => {
+        const dispose = bus.subscribe((live) => {
           if (disabled.has(plugin)) return
+          const event = HOOK_EVENTS[hook] === live.kind ? viewOf(live) : live
           // Not awaited: the bus is synchronous and plugin work runs off the
           // critical path. A handler's rejection is caught like its throw.
           let ret: unknown
@@ -1048,12 +1068,18 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
     }
 
     try {
-      if (args.step === undefined) await plugin.setup(ctx)
-      else await args.step(`${plugin.name}:setup`, async () => plugin.setup?.(ctx))
+      const setup = async (): Promise<void> => plugin.setup?.(ctx)
+      await unlessStopped(
+        args.step === undefined ? setup() : args.step(`${plugin.name}:setup`, setup),
+        args.signal,
+      )
     } catch (err) {
       // Earlier plugins' subscriptions too: the caller never gets the
       // disposer, and a bus that outlives the run would keep them.
       for (const d of disposers) d()
+      // A stop is no refusal of this plugin's: its setup may hold what
+      // its teardown releases, so it is torn down with every other.
+      if (args.signal?.aborted === true) throw err
       throw new PluginSetupError(
         plugin,
         // Masked at the source, as plugin-host.ts's `safe()` does (L-11).

package/src/orchestrator/prepare.ts

@@ -9,7 +9,7 @@
 
 import { existsSync, realpathSync } from 'node:fs'
 import path from 'node:path'
-import type { WorkspaceConfig } from '../config.js'
+import type { InputStability, WorkspaceConfig } from '../config.js'
 import {
   beginRun,
   mark,
@@ -47,6 +47,7 @@ import {
 import {
   buildPackageGraph,
   computeNestedProjectDirs,
+  findProjectConfigs,
   findWorkspaceRoot,
   configuredBaseBranch,
   type LoadReads,
@@ -83,24 +84,26 @@ import {
   discoverProjects,
   gitOfDiscovery,
   graphOfDiscovery,
+  ignoredConfigRefusal,
   loadProjects,
   loadWorkspacePlugins,
   lockOfDiscovery,
   lockReader,
   type LoadedProjects,
+  nestedWorkspacesOf,
 } from './projects.js'
 import { keptByAffected } from './affected-tasks.js'
 import { applyGraphStage } from './graph-stage.js'
 import { keyExcludedDependencies } from './excluded-keys.js'
 import { FingerprintWatch } from './fingerprint-watch.js'
 import type { VxPlugin } from './plugin.js'
-import { memoGraph, type GraphMemo } from './graph-memo.js'
+import { graphCounts, memoGraph, type GraphMemo } from './graph-memo.js'
 import { askIgnoredOutputs, gatedOutputs } from './stable-keys.js'
 import { cacheRefs, currentBranch, resolveCacheScope } from './run-context.js'
 import { createHashCache, type HashCache } from './task-hash.js'
 import { type Logger, warnOf } from '../report/index.js'
 import type { RunOptions } from './options.js'
-import { resolveSetting, runRules } from '../settings.js'
+import { resolveSetting, runRules, settingEnv } from '../settings.js'
 
 export interface PreparedRun {
   workspaceRoot: string
@@ -207,6 +210,12 @@ export interface PreparedRun {
    * `computeTaskHash` call so the same config object isn't re-hashed.
    */
   hashCache: HashCache
+  /**
+   * Each task's count of the tasks downstream of it (`graphCounts`), when
+   * nothing after the graph build can edit `nodes`: counted while git's
+   * blob-size check runs, so `run` reads it instead of counting.
+   */
+  dependents?: ReadonlyMap<string, number>
   /**
    * Reason `nodes` is empty. `null` when the prepared run is ready to
    * execute. Either:
@@ -237,6 +246,26 @@ export interface PreparedRun {
  * empty plan).
  */
 export async function prepareRun(options: RunOptions, log: Logger): Promise<PreparedRun> {
+  return prepareRunLocked(options, log)
+}
+
+/**
+ * `prepareRun`, with `beforeOpen` run once the workspace root is known and
+ * before the cache opens: a run takes its lock there (run.ts), so it never
+ * holds the store while it waits for a `vx cache clean` that holds the lock,
+ * and holds a cache directory with no store (`sharedCacheDir`) shared.
+ * `countDependents`: a run's, which schedules by them (`PreparedRun.dependents`);
+ * a plan never reads them. `planning`: a plan's (`--dry`). With no remote
+ * to probe it opens the cache to read only: no directory, index,
+ * `.gitignore` or row is made.
+ */
+export async function prepareRunLocked(
+  options: RunOptions,
+  log: Logger,
+  beforeOpen?: (workspaceRoot: string, sharedCacheDir: string | undefined) => Promise<void>,
+  countDependents = false,
+  planning = false,
+): Promise<PreparedRun> {
   beginRun()
   mark('startup')
   // A claimed root file is read once. A watch cycle is a new run and reads
@@ -301,8 +330,10 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     ? path.resolve(options.cwd, options.cacheDir)
     : resolveCacheDir(workspaceRoot, workspaceConfig)
   // Before any racy window is judged: a file system behind this process's
-  // clock dated a mid-command edit before the command (fs-clock.ts).
-  measureFsClockLag(cacheDir)
+  // clock dated a mid-command edit before the command (fs-clock.ts). A plan
+  // keys as the run does but may make no cache dir: it measures in `.vx`,
+  // on the workspace's file system, which the workspace file makes exist.
+  measureFsClockLag(planning ? path.join(workspaceRoot, '.vx') : cacheDir)
   // Asked now, read when the cache opens: a repository with no remote is
   // named by its root commit, a git spawn the discovery below overlaps.
   const storeRoot = options.cacheDir ? null : resolveStoreRoot(workspaceRoot, workspaceConfig)
@@ -363,20 +394,51 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     options.remoteReadOnlyByDefault === true &&
     !(options.cache === undefined && namesRemote(workspaceConfig?.cache?.policy))
   const wanted: CachePolicy = readOnly ? { ...asked, remoteWrite: false } : asked
-  const localCache = new Cache(
-    cacheDir,
-    { read: wanted.localRead, write: wanted.localWrite },
-    workspaceRoot,
-    options.artifactCeiling,
-    'open',
-    await storeRoot,
-    {
-      embeddings: (resolveSetting('cache.store.embeddings', workspaceConfig).value ??
-        DEFAULT_STORE.embeddings) as number,
-      decompress: (resolveSetting('cache.store.decompress', workspaceConfig).value ??
-        DEFAULT_STORE.decompress) as boolean,
-    },
-  )
+  const resolvedStore = await storeRoot
+  // A cache directory with no store may be another workspace's too: the
+  // run holds it shared (`holdCacheDir`).
+  await beforeOpen?.(workspaceRoot, resolvedStore === null ? cacheDir : undefined)
+  // A plan with no remote to probe writes nothing: it reads the index as the
+  // run would, one of another schema as the empty one the run's reset
+  // leaves (`'preview'`), and upserts no file-hash memo. One with a remote
+  // keeps the hits its probe finds, for the `vx run` that follows (an
+  // index made for them if need be): that run GETs them before its own
+  // probe answers (2026-10-23).
+  const planReadOnly =
+    planning &&
+    (!wanted.remoteRead ||
+      (options.remoteCache === undefined && !plugins.some((p) => p.cache !== undefined)))
+  const openCache = (): Cache =>
+    new Cache(
+      cacheDir,
+      { read: wanted.localRead, write: wanted.localWrite && !planReadOnly },
+      workspaceRoot,
+      options.artifactCeiling,
+      planReadOnly ? 'preview' : 'open',
+      resolvedStore,
+      {
+        embeddings: (resolveSetting('cache.store.embeddings', workspaceConfig).value ??
+          DEFAULT_STORE.embeddings) as number,
+        decompress: (resolveSetting('cache.store.decompress', workspaceConfig).value ??
+          DEFAULT_STORE.decompress) as boolean,
+      },
+    )
+  // A `vx cache clean` in another checkout holds the shared store alone
+  // until it has deleted it (`attachStore`), as this run's hold keeps a
+  // clean waiting: the run waits its turn, then opens the store there now.
+  let localCache: Cache
+  for (let said = false; ; await Bun.sleep(50)) {
+    try {
+      localCache = openCache()
+      break
+    } catch (err) {
+      if (resolvedStore == null || (err as { code?: unknown }).code !== 'SQLITE_BUSY') throw err
+    }
+    if (!said) {
+      said = true
+      warnOf(log)(`[vx] waiting for a vx cache clean of ${resolvedStore} to finish…`)
+    }
+  }
   const unwritable = localCache.readOnlyNotice()
   if (unwritable !== null) warnOf(log)(`[vx] ${unwritable}`)
   const policy: CachePolicy = unwritable === null ? wanted : { ...wanted, localWrite: false }
@@ -456,6 +518,9 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // a parent's glob that folded (or cleaned) them crossed a boundary the
   // selection drew (X-57).
   const nestedDirsByProject = computeNestedProjectDirs(projectMetas)
+  const nestedWorkspaces = nestedWorkspacesOf(projectMetas)
+  if (nestedWorkspaces.length > 0)
+    outputWalls.set(nestedDirsByProject, computeNestedProjectDirs(projectMetas, nestedWorkspaces))
 
   const candidateProjects = options.projects
     ? options.projects.filter((p) => projects.has(p))
@@ -471,7 +536,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // nothing, exit 0.
   if (options.selectedByDiff === true && candidateProjects.length === 0)
     unresolvedTasks = [...new Set([...tasks.filter((t) => !t.includes('#')), ...unresolvedTasks])]
-  refuseUnlockedConfig(tasks, projects, projectMetas, workspaceRoot)
+  await refuseUnlockedConfig(tasks, projects, projectMetas, workspaceRoot)
   // A scope that loaded no candidate judged no bare name: each is unresolved.
   if (options.projects !== undefined && options.selectedByDiff !== true)
     refuseUnlockedScope(
@@ -514,11 +579,15 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // short name for `@scope/pkg`) was measured against nothing and got no
   // "did you mean". Only a failing run pays for the rest of the workspace.
   let hintProjects: ReadonlyMap<string, ProjectEntry> = projects
+  // So does a bare name where no project in scope declares a task: "no
+  // project declares a task yet" must be true of the workspace, not of the
+  // root project a run from the root selects.
   if (
     unresolvedTasks.some((t) => {
       const at = t.indexOf('#')
       return at > 0 && !projects.has(t.slice(0, at))
-    })
+    }) ||
+    (unresolvedTasks.some((t) => !t.includes('#')) && !declaresAny(projects))
   ) {
     try {
       hintProjects = (
@@ -587,7 +656,14 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // cycle under `vx watch` (item 1029). run() owns both only once this
   // returns.
   try {
-    const hashCache = createHashCache(localCache.foldMemo())
+    const hashCache = createHashCache(
+      localCache.foldMemo(),
+      resolveSetting('outputs.clean', workspaceConfig).value as boolean | undefined,
+      {
+        run: settingEnv('inputs.stability.strategy') as InputStability['strategy'],
+        workspace: workspaceConfig?.inputs?.stability?.strategy,
+      },
+    )
     const fingerprintWatch = new FingerprintWatch(
       workspaceRoot,
       claimed,
@@ -699,11 +775,12 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
         options.affected,
         projects,
         packageGraph,
+        workspaceRoot,
         {
           named: new Set(tasks.filter((t) => t.includes('#'))),
           outright: new Set(options.selectedOutright),
         },
-        options.affectedReasons && { workspaceRoot, reasons: options.affectedReasons },
+        options.affectedReasons && { reasons: options.affectedReasons },
       )
       if (kept.length === 0) return emptyRun('none-affected')
       if (before !== null) {
@@ -790,7 +867,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     const settleIgnored = askIgnoredOutputs(gatedOutputs(nodes, workspaceRoot), workspaceRoot)
     const enumeration = await enumerating
     localCache.holdBlobSizes()
-    await applyGitEnumeration(
+    const applied = applyGitEnumeration(
       enumeration,
       workspaceRoot,
       projectDirs,
@@ -798,6 +875,19 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       usesWorkspaceInputs,
       localCache,
     )
+    // The dependents count while the blob-size check's `cat-file` runs: the
+    // thread waited ~80 ms on it in a cold 8,002-task run, and counting
+    // after it, before the first task, took 40 ms (2026-11-07). Only when
+    // nothing below edits the nodes: a graph or key hook, or
+    // `--exclude-dependencies`.
+    const excluding =
+      options.excludeDependencies !== undefined &&
+      (options.excludeDependencies === 'all' || options.excludeDependencies.length > 0)
+    const dependents =
+      !countDependents || (hasGraphHook && !hooksFirst) || hasHook(plugins, 'key') || excluding
+        ? undefined
+        : graphCounts(nodes, hashCache.folds, hashCache.graph)
+    await applied
     await settleIgnored(gitFilesCache)
     mark('git enumeration')
     if (hasGraphHook && !hooksFirst) await graphStage()
@@ -909,6 +999,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       nestedDirsByProject,
       gitFilesCache,
       hashCache,
+      ...(dependents !== undefined ? { dependents } : {}),
       workspaceProjectCount: projectMetas.length,
       empty: nodes.size === 0 ? 'empty-graph' : null,
     }
@@ -938,6 +1029,13 @@ async function declaredNowhere(
   return undeclaredIn(unresolved, all.projects)
 }
 
+/** Whether any project in `projects` declares a task: its default `build` is none. */
+function declaresAny(projects: LoadedProjects['projects']): boolean {
+  for (const p of projects.values())
+    for (const task of Object.values(p.config.tasks ?? {})) if (!isDefaultBuild(task)) return true
+  return false
+}
+
 /**
  * The bare names in `unresolved` no project in `projects` declares; `a#b`
  * forms pass through. Every project has a `build`, its default one if
@@ -1008,6 +1106,23 @@ function pruneToClosure(nodes: Map<string, TaskNode>, roots: ReadonlySet<string>
 export const namesRemote = (spec: string | undefined): boolean =>
   spec !== undefined && /remote:[rw]/.test(spec)
 
+/** Each run's output walls, by its `nestedDirsByProject`, when it has a nested workspace. */
+const outputWalls = new WeakMap<ReadonlyMap<string, string[]>, ReadonlyMap<string, string[]>>()
+
+/**
+ * Where each project's outputs stop: its nested projects and every nested
+ * workspace under it. Its inputs stop at the projects alone: a task may
+ * read a nested workspace's files (a git worktree checked out under
+ * `src/` holds one), so folding them costs a miss, and leaving them out
+ * a stale hit; cleaning them deleted another workspace's work. The map
+ * itself when there is no nested workspace.
+ */
+export function outputWallsOf(
+  nestedDirsByProject: ReadonlyMap<string, string[]>,
+): ReadonlyMap<string, string[]> {
+  return outputWalls.get(nestedDirsByProject) ?? nestedDirsByProject
+}
+
 /**
  * The workspace's `cache.policy`, parsed: the schema checks only its shape,
  * since the grammar lives in the cache module the workspace module may not
@@ -1022,7 +1137,7 @@ export function workspaceCachePolicy(
     return parseCachePolicy(spec)
   } catch (err) {
     throw new UserError(
-      `.vx/workspace: \`cache.policy\`: ${err instanceof Error ? err.message : String(err)}`,
+      `.vx/workspace: \`cache.policy\` ${err instanceof Error ? err.message : String(err)}`,
       'VX_E_CONFIG',
     )
   }
@@ -1031,13 +1146,17 @@ export function workspaceCachePolicy(
 /** A config no locked project has, looked for only when the lock holds none. */
 function unlockedConfigOf(
   configured: readonly unknown[],
-  metas: ReadonlyArray<{ dir: string }>,
+  metas: ReadonlyArray<{ name: string; dir: string }>,
   workspaceRoot: string,
 ): string | undefined {
   if (configured.length > 0) return undefined
   for (const m of metas) {
     const config = PROJECT_CONFIG_FILENAMES.find((n) => existsSync(path.join(m.dir, n)))
-    if (config !== undefined) return relPosix(workspaceRoot, path.join(m.dir, config))
+    if (config === undefined) continue
+    const file = path.join(m.dir, config)
+    // `vx lock` never reads it: the hint would send the user to it for nothing.
+    if (ignoredConfigRefusal(workspaceRoot, m, file) === undefined)
+      return relPosix(workspaceRoot, file)
   }
   return undefined
 }
@@ -1048,12 +1167,12 @@ function unlockedConfigOf(
  * one that runs nothing: ran, `c#build` was 0 tasks, exit 0, where a
  * renamed task gets "run `vx lock`" (Growth, lock drift).
  */
-function refuseUnlockedConfig(
+async function refuseUnlockedConfig(
   tasks: readonly string[],
   projects: ReadonlyMap<string, ProjectEntry>,
   metas: ReadonlyArray<{ name: string; dir: string; configPath?: string | null }>,
   workspaceRoot: string,
-): void {
+): Promise<void> {
   for (const spec of tasks) {
     const at = spec.indexOf('#')
     if (at < 0) continue
@@ -1061,12 +1180,13 @@ function refuseUnlockedConfig(
     const entry = projects.get(name)
     // No entry: a package the lock holds no project for, whose config came after it.
     if (entry !== undefined && !isDefaultBuild(entry.config.tasks?.[spec.slice(at + 1)])) continue
-    const config = unlockedConfig(name, metas)
+    const config =
+      unlockedConfig(name, metas) ??
+      (metas.some((m) => m.name === name)
+        ? undefined
+        : await unlockedDir(name, metas, workspaceRoot))
     if (config === undefined) continue
-    throw new UserError(
-      `${spec}: ${relPosix(workspaceRoot, config)} is not in the lock yet — run \`vx lock\``,
-      'VX_E_LOCK',
-    )
+    throw new UserError(`${spec}: ${notLockedYet(workspaceRoot, config, metas, name)}`, 'VX_E_LOCK')
   }
 }
 
@@ -1089,13 +1209,28 @@ function refuseUnlockedScope(
   for (const name of selected) {
     const config = unlockedConfig(name, metas)
     if (config === undefined) continue
-    throw new UserError(
-      `${spec}: ${relPosix(workspaceRoot, config)} is not in the lock yet — run \`vx lock\``,
-      'VX_E_LOCK',
-    )
+    throw new UserError(`${spec}: ${notLockedYet(workspaceRoot, config, metas, name)}`, 'VX_E_LOCK')
   }
 }
 
+/**
+ * Why the lock holds no `config`: git ignores it, in a directory a
+ * `discover` plugin made a project, which `vx lock` cannot fix; else it
+ * came after the lock.
+ */
+function notLockedYet(
+  workspaceRoot: string,
+  config: string,
+  metas: ReadonlyArray<{ name: string; dir: string }>,
+  name: string,
+): string {
+  const meta = metas.find((m) => m.name === name)
+  return (
+    (meta === undefined ? undefined : ignoredConfigRefusal(workspaceRoot, meta, config)) ??
+    `${relPosix(workspaceRoot, config)} is not in the lock yet — run \`vx lock\``
+  )
+}
+
 /** The config file in a project's directory the lock holds none for. */
 function unlockedConfig(
   name: string,
@@ -1108,6 +1243,27 @@ function unlockedConfig(
   return config === undefined ? undefined : path.join(meta.dir, config)
 }
 
+/**
+ * The config `vx lock` would find in the directory a name no project has
+ * reads as (`packages/d`, `c`): with no discover plugin a config written
+ * after the lock makes no project, so `unlockedConfig` never sees it.
+ * Asked only for a name that matches nothing, a run or `vx show` about to
+ * be refused; the listing is paid only when the directory holds a config.
+ */
+export async function unlockedDir(
+  name: string,
+  metas: ReadonlyArray<{ dir: string }>,
+  workspaceRoot: string,
+): Promise<string | undefined> {
+  const dir = path.resolve(workspaceRoot, name)
+  // A project's directory typed for its name is that project, hinted as such.
+  if (!dir.startsWith(workspaceRoot + path.sep) || metas.some((m) => m.dir === dir))
+    return undefined
+  if (!PROJECT_CONFIG_FILENAMES.some((n) => existsSync(path.join(dir, n)))) return undefined
+  const { configs } = await findProjectConfigs(workspaceRoot)
+  return configs.find((c) => c.dir === dir)?.configPath
+}
+
 /**
  * Each remote's `open`, in declared order, for the ones the policy lets read
  * or write. One at a time: two that ask on the terminal must not interleave.