@vzn/vx 0.0.641 → 0.0.642

package/src/orchestrator/plugin-host.ts

@@ -381,6 +381,36 @@ export async function claimedAffected(
   return names
 }
 
+/**
+ * The files a claimed file names that its plugin keys too
+ * (`FingerprintClaim.extraFiles`); `undefined` when it names none it can
+ * answer for, and a plugin that throws is refused by its name.
+ */
+export function claimedExtraFiles(
+  plugin: VxPlugin,
+  file: string,
+  bytes: Uint8Array,
+): readonly string[] | undefined {
+  const read = plugin.fingerprint?.extraFiles
+  if (read === undefined) return undefined
+  let names: unknown
+  try {
+    names = read.call(plugin.fingerprint, file, bytes)
+  } catch (err) {
+    throw new UserError(
+      maskedLine(
+        `plugin '${plugin.name}' failed in fingerprint: ${err instanceof Error ? err.message : String(err)}`,
+      ),
+    )
+  }
+  if (!Array.isArray(names) || names.some((n) => typeof n !== 'string')) {
+    throw new UserError(
+      `plugin '${plugin.name}' failed in fingerprint: extraFiles returned ${describeValue(names)}, not a list of paths`,
+    )
+  }
+  return names as string[]
+}
+
 /** What a run hands the `schedule` stage: a step per plugin, and where refined weights go. */
 export interface ScheduleRun {
   readonly step?: <T>(id: string, work: () => Promise<T>) => Promise<T>
@@ -548,6 +578,7 @@ export async function resolveCache(
     assertShape(plugin, 'cache', remote, REMOTE_CACHE_METHODS, 'a remote cache layer')
     const entry: ResolvedRemote = {
       remote,
+      plugin: plugin.name,
       read: policy.remoteRead,
       write: policy.remoteWrite,
       onError: (err) => ctx.warn(`[vx] plugin '${plugin.name}': ${err.message}`),

package/src/orchestrator/plugin.ts

@@ -20,7 +20,7 @@ import {
 import { PLUGIN_PACKAGE, type ProjectConfig, type WorkspaceConfig } from '../config.js'
 import type { TaskExecutor } from '../exec/index.js'
 import type { TaskNode, TaskOutcome, TaskStatus } from '../graph/index.js'
-import { maskedLine, nearest, UserError } from '../util/index.js'
+import { maskedLine, nearest, type PluginSecrets, SecretBroker, UserError } from '../util/index.js'
 import type { ProjectMeta } from '../workspace/index.js'
 import type { EventBus, Logger, RunStartInfo } from '../report/index.js'
 import type { CiContext } from './run-context.js'
@@ -285,8 +285,12 @@ interface BaseContext {
   warn(message: string): void
 }
 
-/** What `setup` receives: the run's lifecycle, observe-only. */
-export interface PluginSetupContext extends BaseContext {
+/**
+ * What `setup` receives: the run's lifecycle, observe-only, and the
+ * plugin's keychain (`secret`, `forgetSecret`): setup runs before the
+ * status line, so a prompt there is seen.
+ */
+export interface PluginSetupContext extends BaseContext, PluginSecrets {
   /** This plugin's entries in the workspace's cache (`PluginCache`). */
   readonly cache: PluginCache
   /** The run is on CI (`CI` set, or a provider core detects). */
@@ -419,6 +423,15 @@ export interface FingerprintClaim {
     change: FingerprintChange,
     ctx: FingerprintContext,
   ): Iterable<string> | undefined | Promise<Iterable<string> | undefined>
+  /**
+   * The workspace-relative files a claimed file's bytes name that the
+   * plugin's key reads too: `bun.lock`'s patch files, which it names by
+   * path and hashes nowhere, or a `file:` dependency's directory. A change
+   * to one, or under one, asks `affected` about the file naming it, with
+   * `change.extras`. Without it, a `bun.lock` patch edit selects every
+   * project.
+   */
+  extraFiles?(file: string, bytes: Uint8Array): readonly string[]
 }
 
 export interface FingerprintChange {
@@ -426,6 +439,15 @@ export interface FingerprintChange {
   readonly file: string
   readonly before: Uint8Array | null
   readonly after: Uint8Array | null
+  /**
+   * Each changed `extraFiles` entry, as the claimant names it, at the base
+   * ref and in the working tree. A directory's sides are not its bytes:
+   * they differ because a file under it changed.
+   */
+  readonly extras?: ReadonlyMap<
+    string,
+    { readonly before: Uint8Array | null; readonly after: Uint8Array | null }
+  >
 }
 
 export interface FingerprintContext extends BaseContext {
@@ -695,6 +717,8 @@ export interface InstallPluginsArgs {
   ci?: boolean
   /** Default null. */
   branch?: string | null
+  /** The run's secrets; default: the OS keychain and this terminal. */
+  secrets?: SecretBroker
   /** Each setup as the step `<plugin>:setup`; default: untimed. */
   step?: <T>(id: string, work: () => Promise<T>) => Promise<T>
 }
@@ -726,6 +750,7 @@ export class PluginSetupError extends UserError {
 export async function installPlugins(args: InstallPluginsArgs): Promise<() => void> {
   const { plugins, bus, workspaceRoot, cacheDir } = args
   const warn = args.warn ?? ((m) => console.error(m))
+  const secrets = args.secrets ?? new SecretBroker(args.ci ?? false, warn)
   const disposers: Array<() => void> = []
   // By object, not name: one package can export two plugins.
   const disabled = new Set<Plugin>()
@@ -754,6 +779,7 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
       cacheDir,
       warn,
       cache: args.cache?.(plugin.name) ?? absentPluginCache,
+      ...secrets.for(plugin.name),
       ci: args.ci ?? false,
       branch: args.branch ?? null,
       // A subscription made past the hooks leaves with the run like a

package/src/orchestrator/prepare.ts

@@ -7,9 +7,10 @@
 // closes at the bottom of execution, `planRun()` does so via
 // try/finally around its plan() call.
 
+import { existsSync } from 'node:fs'
 import path from 'node:path'
 import type { WorkspaceConfig } from '../config.js'
-import { beginRun, mark, nearest, UserError } from '../util/index.js'
+import { beginRun, mark, nearest, relPosix, type SecretBroker, UserError } from '../util/index.js'
 import {
   Cache,
   type CacheLayer,
@@ -40,6 +41,7 @@ import {
   cacheScopeEnvError,
   isCacheScope,
   type LoadReads,
+  PROJECT_CONFIG_FILENAMES,
   readClaimedFiles,
   resolveCacheDir,
   resolveStoreRoot,
@@ -111,6 +113,8 @@ export interface PreparedRun {
   hasRemoteLayer: boolean
   /** `--cache-policy` with the workspace's `cacheScope` applied: what the layers were built under. */
   cachePolicy: CachePolicy
+  /** The run's remotes in declared order, as the policy gates each; `openRemotes` turns one off. */
+  remotes: ResolvedRemote[]
   /**
    * Scheduling priorities from plugins' `schedule` stage (task id → weight,
    * merged over the structural baseline by the scheduler). Empty when no
@@ -325,16 +329,18 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   const readOnly =
     options.remoteReadOnlyByDefault === true &&
     !(options.cache === undefined && namesRemote(workspaceConfig?.cache?.policy))
-  const policy: CachePolicy = readOnly ? { ...asked, remoteWrite: false } : asked
+  const wanted: CachePolicy = readOnly ? { ...asked, remoteWrite: false } : asked
   const localCache = new Cache(
     cacheDir,
-    { read: policy.localRead, write: policy.localWrite },
+    { read: wanted.localRead, write: wanted.localWrite },
     workspaceRoot,
     options.artifactCeiling,
     'open',
     await storeRoot,
   )
-  localCache.assertWritable()
+  const unwritable = localCache.readOnlyNotice()
+  if (unwritable !== null) warnOf(log)(`[vx] ${unwritable}`)
+  const policy: CachePolicy = unwritable === null ? wanted : { ...wanted, localWrite: false }
   // The root files the plugins claim (`VxPlugin.fingerprint`), whose bytes
   // their claimants fold: read now so a task that rewrites one is caught.
   const fingerprintsAt = Date.now()
@@ -405,6 +411,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // A dependant's `^build` still reaches it, and `lib#build` names it.
   const requested = expandRequested(tasks, candidateProjects, projects, isDefaultBuild)
   let unresolvedTasks = unresolvedRequests(tasks, candidateProjects, projects, isDefaultBuild)
+  refuseUnlockedConfig(tasks, projects, projectMetas, workspaceRoot)
   if (options.selectedByDiff === true && unresolvedTasks.some((t) => !t.includes('#'))) {
     // A name a loaded project declares is no typo, whether or not the load
     // was whole: an unaffected dependency loaded for the closure declared
@@ -508,7 +515,7 @@ 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()
+    const hashCache = createHashCache(localCache.foldMemo())
     const fingerprintWatch = new FingerprintWatch(
       workspaceRoot,
       claimed,
@@ -527,6 +534,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       localCache,
       hasRemoteLayer,
       cachePolicy: policy,
+      remotes,
       keepRunEntry: undefined,
       priorities: () => Promise.resolve(new Map()),
       branch,
@@ -775,6 +783,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       localCache,
       hasRemoteLayer,
       cachePolicy: policy,
+      remotes,
       priorities,
       branch,
       cacheFor,
@@ -906,3 +915,63 @@ function workspaceCachePolicy(config: WorkspaceConfig | null | undefined): Cache
     )
   }
 }
+
+/**
+ * A `project#build` naming the default `build` of a project the lock holds
+ * no config for, while its directory holds one, asks for that config's task, not
+ * 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(
+  tasks: readonly string[],
+  projects: ReadonlyMap<string, ProjectEntry>,
+  metas: ReadonlyArray<{ name: string; configPath?: string | null }>,
+  workspaceRoot: string,
+): void {
+  for (const spec of tasks) {
+    const at = spec.indexOf('#')
+    if (at < 0) continue
+    const name = spec.slice(0, at)
+    const entry = projects.get(name)
+    if (entry === undefined || !isDefaultBuild(entry.config.tasks?.[spec.slice(at + 1)])) continue
+    const locked = metas.find((m) => m.name === name)?.configPath
+    if (typeof locked === 'string' && locked !== '') continue
+    const config = PROJECT_CONFIG_FILENAMES.find((n) => existsSync(path.join(entry.dir, n)))
+    if (config === undefined) continue
+    throw new UserError(
+      `${spec}: ${relPosix(workspaceRoot, path.join(entry.dir, config))} is not in the lock yet — run \`vx lock\``,
+    )
+  }
+}
+
+/**
+ * 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.
+ * A throw warns through the remote's `onError` (naming its plugin) and
+ * turns that remote off; the run goes on, as after any remote failure.
+ * True when that left the run no remote at all.
+ */
+export async function openRemotes(
+  remotes: readonly ResolvedRemote[],
+  ci: boolean,
+  secrets: SecretBroker,
+): Promise<boolean> {
+  let closed = false
+  for (const entry of remotes) {
+    if (entry.remote.open === undefined || !(entry.read || entry.write)) continue
+    try {
+      await entry.remote.open({
+        ci,
+        warn: (message) => entry.onError?.(new Error(message)),
+        ...secrets.for(entry.plugin ?? 'vx'),
+      })
+    } catch (err) {
+      entry.read = false
+      entry.write = false
+      const e = err instanceof Error ? err : new Error(String(err))
+      entry.onError?.(e)
+      closed = true
+    }
+  }
+  return closed && !remotes.some((r) => r.read || r.write)
+}

package/src/orchestrator/projects.ts

@@ -127,11 +127,16 @@ export async function discoverProjects(
       (e) => e.changed,
       () => null,
     )
+  const byDir = new Map(projects.map((p) => [p.dir, p]))
   const edges = await applyDiscoverHooks(
     plugins,
     projects,
     { workspaceRoot, cacheDir, warn, worktreeChanges },
-    (entry, plugin) => discoveredProject(workspaceRoot, projects, entry, plugin.name),
+    async (entry, plugin) => {
+      const found = await discoveredProject(workspaceRoot, byDir, entry, plugin.name)
+      if (found.added) byDir.set(found.meta.dir, found.meta)
+      return found
+    },
   )
   checkProjectNames(workspaceRoot, projects)
   linkDiscoveredEdges(workspaceRoot, projects, edges)

package/src/orchestrator/run.ts

@@ -49,6 +49,7 @@ import {
   isUserError,
   detectColors,
   type ColorSupport,
+  SecretBroker,
 } from '../util/index.js'
 import { keyedProjects } from './keyed-projects.js'
 import { isDefaultBuild } from './projects.js'
@@ -87,7 +88,7 @@ import { isPassStatus } from '../graph/index.js'
 import type { RunContextRecord } from './telemetry.js'
 import { plan, type RunPlan } from './plan.js'
 import type { AffectedReason } from './affected-tasks.js'
-import { prepareRun, type PreparedRun } from './prepare.js'
+import { openRemotes, prepareRun, type PreparedRun } from './prepare.js'
 import { acquireRunLock } from './run-lock.js'
 import { terminateChildren } from './signals.js'
 import { runStop } from './run-stop.js'
@@ -466,6 +467,15 @@ async function runOnBus(
           failures: keepRun.failures,
           traffic: prepared.localCache.traffic,
         })
+  // Before setup and the status line: a remote's `open` may ask on the terminal.
+  const secrets = new SecretBroker(
+    ciContext.ci,
+    warnOf(log),
+    undefined,
+    undefined,
+    terminal === null ? undefined : () => terminal.holdStatus(),
+  )
+  const remotesClosed = await openRemotes(prepared.remotes, ciContext.ci, secrets)
   try {
     disposePlugins = await installPlugins({
       plugins: prepared.plugins,
@@ -476,6 +486,7 @@ async function runOnBus(
       cache: prepared.cacheFor,
       ci: ciContext.ci,
       branch: prepared.branch(),
+      secrets,
       step,
     })
   } catch (err) {
@@ -592,6 +603,7 @@ async function runOnBus(
     handsTerminal: holders.size > 0,
     teardowns: prepared.plugins.filter((p) => p.teardown).length,
     onStop: () => {
+      log.runStop?.()
       stopRuntimeProbes(hashCache.runtime, hashCache.workspaceRuntime)
       cache.stopUploads?.()
       keeper?.stop()
@@ -634,13 +646,15 @@ async function runOnBus(
   try {
     const runStartHrTimeNs = process.hrtime.bigint()
     const endedAtMsAtStart = Date.now()
-    const remoteCacheEnabled = prepared.hasRemoteLayer
+    // Every remote turned off by its `open` is no remote: a task must not clean
+    // its outputs for a save that goes nowhere.
+    const remoteCacheEnabled = prepared.hasRemoteLayer && !remotesClosed
     // Normalised ONCE so every consumer — execute-task, the dedup
     // predicate, the recorded invocation row — reads the policy that
     // actually governed the run. Reading the raw request here made tasks
     // clean their outputs before every exec for a save that never
     // happened.
-    const policy: CachePolicy = effectiveCachePolicy(prepared.cachePolicy, prepared.hasRemoteLayer)
+    const policy: CachePolicy = effectiveCachePolicy(prepared.cachePolicy, remoteCacheEnabled)
     if (options.remoteRequested === true && !prepared.hasRemoteLayer) {
       warnOf(log)(
         'vx: --cache-policy named the remote cache, but no cache plugin in .vx/workspace.* supplies one — the remote axes are off for this run',
@@ -794,6 +808,7 @@ async function runOnBus(
       },
       concurrency,
       workspaceProjectCount,
+      runId: undefined as string | undefined,
     }
 
     // Asked only when a plugin declares `output`: a plain run pays nothing.
@@ -810,6 +825,8 @@ async function runOnBus(
 
     // Lifecycle hooks drive the default logger's dynamic status line
     // (TTY-only); custom loggers may ignore them.
+    // The status line starts here: a prompt now would be drawn over.
+    secrets.closePrompts()
     log.runStart?.({
       total: taskCount,
       concurrency,
@@ -817,18 +834,22 @@ async function runOnBus(
       context: runContext,
       startedAtMs: endedAtMsAtStart,
     })
-    // The live region's end-of-run forecast. The logger asks only if its
-    // region is still up a second in, so a warm run never reads history.
-    terminal?.forecast(async () => {
-      const ids: string[] = []
-      for (const n of nodes.values()) if (!isGroupTask(n)) ids.push(n.id)
-      const p50s = await new LocalHistoryProvider(
-        prepared.localCache.dbHandle(),
-        undefined,
-        prepared.branch(),
-      ).p50sFor(ids)
-      return createForecast(nodes, p50s, concurrency)
-    })
+    // The live region's forecast: the graph's from the first free row, and
+    // history's only if the region is still up a second in, so a warm run
+    // never reads history.
+    terminal?.forecast(
+      () => createForecast(nodes, new Map(), concurrency),
+      async () => {
+        const ids: string[] = []
+        for (const n of nodes.values()) if (!isGroupTask(n)) ids.push(n.id)
+        const p50s = await new LocalHistoryProvider(
+          prepared.localCache.dbHandle(),
+          undefined,
+          prepared.branch(),
+        ).p50sFor(ids)
+        return createForecast(nodes, p50s, concurrency)
+      },
+    )
 
     // Remote-only: kick off background prefetches so remote-GET latency
     // overlaps execution. Fire-and-forget — execution starts on the next
@@ -1269,6 +1290,7 @@ async function runOnBus(
       })
     }
     mark('record history')
+    runContext.runId = runId
     // Drain any still-in-flight background prefetches before closing the
     // cache handle — a prefetch ingesting into a closed SQLite DB would
     // throw. Tasks that resolved as local hits never awaited their

package/src/orchestrator/sandbox-request.ts

@@ -7,7 +7,7 @@ import { existsSync } from 'node:fs'
 import { lstat, mkdir, readdir, realpath, rm, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import path from 'node:path'
-import type { ExecConfig, SandboxConfig } from '../config.js'
+import type { ExecConfig } from '../config.js'
 import {
   bindableWrites,
   initSandbox,
@@ -289,53 +289,6 @@ export async function sandboxRequestFor(
   return { sandbox: request, placeholders, withheld: links.withheld }
 }
 
-/**
- * Whether a sandboxed task could read `real` (a canonical path inside its
- * project): under one of its read or write grants or its `node_modules`,
- * and not behind a wall. vx packs a symlinked output as its target's
- * bytes, outside the sandbox, so a link the task planted to a file it was
- * denied (`dist/x -> ../.env` under `read: ['src/']`) packed that file
- * into the cache wherever creating the link went unseen: seatbelt, or
- * Linux untraced. The grants are matched as written, not expanded: a
- * glob's hit made by the task itself counts.
- */
-export function sandboxReadable(
-  node: TaskNode,
-  sandbox: SandboxConfig,
-  workspaceRoot: string,
-  nested: readonly string[] = [],
-): (real: string) => boolean {
-  const projectReal = toRealPath(node.projectDir)
-  const at = (p: string): string =>
-    p.startsWith('~')
-      ? path.join(homedir(), p.slice(1))
-      : path.isAbsolute(p)
-        ? p
-        : path.join(projectReal, p)
-  const grants = [...(sandbox.allow?.read ?? []), ...(sandbox.allow?.write ?? [])].map(at)
-  const literals = [
-    ...grants.filter(isMountableLiteral).map((g) => toRealPath(g.replace(/\/+$/, '') || '/')),
-    toRealPath(path.join(node.projectDir, 'node_modules')),
-    toRealPath(path.join(workspaceRoot, 'node_modules')),
-  ]
-  const globs = grants.filter((g) => !isMountableLiteral(g)).map((g) => new Bun.Glob(g))
-  const walls = [
-    ...nested,
-    path.join(workspaceRoot, '.git'),
-    path.join(workspaceRoot, '.vx', 'cache'),
-  ].map(toRealPath)
-  return (real) => {
-    if (walls.some((w) => atOrUnder(real, w))) return false
-    if (literals.some((l) => atOrUnder(real, l))) return true
-    // A directory a glob matches is granted whole.
-    for (let p = real; atOrUnder(p, projectReal); p = path.dirname(p)) {
-      if (globs.some((g) => g.match(p))) return true
-      if (p === projectReal) break
-    }
-    return false
-  }
-}
-
 /**
  * The sandbox half of the request, plus the empty files vx created so a
  * literal write grant had something to bind (`placeholders`). They are

package/src/orchestrator/save-lane.ts

@@ -12,22 +12,29 @@
 export interface SaveLane {
   /**
    * Start `save` now if the lane has room, else when one finishes. Resolves
-   * once the save has settled — a failure is reported and resolves too —
-   * for the one reader that must wait for the entry: a duplicate of the
-   * same task in another run (admission's in-flight join).
+   * once the save has settled, true when the entry landed — a failure is
+   * reported and resolves false — for the readers that must know: the
+   * task's outcome, and a duplicate of the same task in another run
+   * (admission's in-flight join).
    */
-  defer(save: () => Promise<void>): Promise<void>
+  defer(save: () => Promise<void>): Promise<boolean>
 }
 
 export function createSaveLane(cap: number, onError: (err: unknown) => void): SaveLane {
-  const queue: Array<{ save: () => Promise<void>; settle: () => void }> = []
+  const queue: Array<{ save: () => Promise<void>; settle: (stored: boolean) => void }> = []
   let running = 0
-  const start = (save: () => Promise<void>, settle: () => void): void => {
+  const start = (save: () => Promise<void>, settle: (stored: boolean) => void): void => {
     void save()
-      .catch(onError)
-      .then(() => {
+      .then(
+        () => true,
+        (err: unknown) => {
+          onError(err)
+          return false
+        },
+      )
+      .then((stored) => {
         running--
-        settle()
+        settle(stored)
         const next = queue.shift()
         if (next !== undefined) start(next.save, next.settle)
       })
@@ -35,7 +42,7 @@ export function createSaveLane(cap: number, onError: (err: unknown) => void): Sa
   }
   return {
     defer(save) {
-      return new Promise<void>((settle) => {
+      return new Promise<boolean>((settle) => {
         if (running < cap) start(save, settle)
         else queue.push({ save, settle })
       })

package/src/orchestrator/signals.ts

@@ -126,9 +126,11 @@ export function forwardSignals(args: {
   const everyChild = (): Child[] => [...args.liveChildren, ...args.persistentRegistry.values()]
   const exit = (signal: StopSignal): never => {
     // The run's own end already flushed the log; a second signal cut it
-    // short, so the failure frames it holds print now (idempotent).
+    // short, so the failure frames it holds print now (idempotent), and
+    // the live region goes so a terminal keeps no frozen one.
     try {
       args.log.runEnd?.()
+      args.log.runDone?.()
     } catch {
       // teardown must not throw on the way out
     }
@@ -158,15 +160,10 @@ export function forwardSignals(args: {
     if (stopping !== undefined) exit(stopping)
     stopping = signal
     claimExitForSignal()
-    // Clear the live worker/status region BEFORE exiting so a TTY isn't
-    // left with a frozen region in the scrollback. Only the region: the
-    // tasks this stop aborts still list as rows, above the failure frames
-    // the run's own end prints.
-    try {
-      args.log.runDone?.()
-    } catch {
-      // teardown must not throw on the way out
-    }
+    // The live region stays: the stop marks its rows `stopping` (run.ts's
+    // onStop), and the run's own end replaces it with the footer. Cleared
+    // at once, it left a blank screen for as long as the stop took (M,
+    // 2026-10-17).
     args.stop(signal)
     void settleWithin(args.done, args.boundMs)
       // The run's output may still be in the pipe: `process.exit` drops