@vzn/vx 0.0.641 → 0.0.643

package/src/orchestrator/lockfile-claim.ts

@@ -39,7 +39,9 @@ export interface LockfileClaimOptions {
    * the lockfile does not pin (bun.lock's `patchedDependencies` names a patch
    * file and records no hash of it). Their content hashes ('' when absent)
    * reach `digest` as `files` and join the memo's identity, so an edited
-   * patch moves the key (item 1014). Called only when the memo misses.
+   * patch moves the key (item 1014). A directory (a `file:` dependency the
+   * install copies) hashes every file under it but `node_modules` and
+   * `.git`. Called only when the memo misses.
    */
   readonly extraFiles?: (text: string) => readonly string[]
   /** Folded into the memo's identity: bump when `digest` folds differently. */
@@ -109,13 +111,33 @@ interface Memo {
 /** A root-relative extra file's content hash, '' when absent; a path leaving the root is never read. */
 async function hashExtra(workspaceRoot: string, rel: string): Promise<string> {
   if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) return 'outside-root'
+  const abs = path.join(workspaceRoot, rel)
   try {
-    return xxh3hex(await Bun.file(path.join(workspaceRoot, rel)).bytes())
-  } catch {
+    return xxh3hex(await Bun.file(abs).bytes())
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'EISDIR') return hashDir(abs)
     return ''
   }
 }
 
+/**
+ * Every file under `dir` but its `node_modules` and `.git`, as `rel\0hash`
+ * lines in sorted order. Links are followed: a linked file is what a task
+ * reads, and the scan skipped it, so an edit to its target moved no key.
+ */
+async function hashDir(dir: string): Promise<string> {
+  const rels: string[] = []
+  const scan = { cwd: dir, dot: true, onlyFiles: true, followSymlinks: true }
+  for await (const rel of new Bun.Glob('**').scan(scan)) {
+    if (!rel.split('/').some((s) => s === 'node_modules' || s === '.git')) rels.push(rel)
+  }
+  rels.sort()
+  const lines = await Promise.all(
+    rels.map(async (rel) => `${rel}\0${xxh3hex(await Bun.file(path.join(dir, rel)).bytes())}`),
+  )
+  return `dir\0${xxh3hex(lines.join('\n'))}`
+}
+
 /**
  * A file's identity for the in-process gate, as `Cache.hashFile`'s memo
  * keys one: size and mtime alone kept the digests of a lockfile or patch
@@ -126,9 +148,16 @@ function identityOf(st: { size: number; mtimeMs: number; ctimeMs: number; ino: n
   return `${st.size}:${st.mtimeMs}:${st.ctimeMs}:${st.ino}`
 }
 
+// A directory's own stat moves only when an entry is added or removed, not
+// when a file in it is edited: its identity is its content hash.
 async function statsOf(workspaceRoot: string, rels: readonly string[]): Promise<string[]> {
   return Promise.all(
-    rels.map((rel) => stat(path.join(workspaceRoot, rel)).then(identityOf, () => 'gone')),
+    rels.map((rel) =>
+      stat(path.join(workspaceRoot, rel)).then(
+        (st) => (st.isDirectory() ? hashExtra(workspaceRoot, rel) : identityOf(st)),
+        () => 'gone',
+      ),
+    ),
   )
 }
 
@@ -262,15 +291,29 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
         // lockfile is broken" and "the base commit's is" — a migration
         // commit hits the second, and the bare parser message named
         // neither (2026-09-20).
-        const sideOf = (bytes: Uint8Array, side: string): ReadonlyMap<string, string> => {
+        // A changed extra file is folded by its content on each side; one
+        // left out is the same on both, so it moves no digest either way.
+        const extrasOf = (pick: 'before' | 'after'): Map<string, string> => {
+          const out = new Map<string, string>()
+          for (const [rel, sides] of change.extras ?? []) {
+            const bytes = sides[pick]
+            out.set(rel, bytes === null ? '' : xxh3hex(bytes))
+          }
+          return out
+        }
+        const sideOf = (
+          bytes: Uint8Array,
+          pick: 'before' | 'after',
+          side: string,
+        ): ReadonlyMap<string, string> => {
           try {
-            return digest(decode(bytes), new Map())
+            return digest(decode(bytes), extrasOf(pick))
           } catch (err) {
             throw new Error(`${err instanceof Error ? err.message : String(err)} (${side})`)
           }
         }
-        const before = sideOf(change.before, `as of the base ref`)
-        const after = sideOf(change.after, `in the working tree`)
+        const before = sideOf(change.before, 'before', `as of the base ref`)
+        const after = sideOf(change.after, 'after', `in the working tree`)
         const names: string[] = []
         for (const p of ctx.projects) {
           const importer = importerOf(ctx.workspaceRoot, p.dir)
@@ -278,6 +321,9 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
         }
         return names
       },
+      ...(options.extraFiles !== undefined
+        ? { extraFiles: (_file: string, bytes: Uint8Array) => options.extraFiles!(decode(bytes)) }
+        : {}),
     },
     async key(task, ctx) {
       const digests = await loadOnce(ctx)

package/src/orchestrator/miss-save.ts

@@ -12,6 +12,7 @@ import path from 'node:path'
 import {
   type CacheLayer,
   type GitFilesCache,
+  resolveOutputTree,
   resolveOutputs,
   resolveWorkspaceOutputs,
   WORKSPACE_OUTPUT_PREFIX,
@@ -51,7 +52,9 @@ export function entryHolds(
 ): (files: readonly string[], rows: ReadonlyArray<{ path: string }>) => boolean {
   return (files, rows) => {
     const expected = new Set(
-      rows.map((r) => r.path).filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX)),
+      rows
+        .map((r) => r.path)
+        .filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX) && !p.endsWith('/')),
     )
     const seen = new Set(files)
     if ((node.addsToOutputsOf?.length ?? 0) > 0) return [...expected].every((p) => seen.has(p))
@@ -111,8 +114,6 @@ export interface SaveMissArgs {
   ownOutputFiles?: string[] | undefined
   /** `ownOutputFiles` for `cache.outputs.workspaceFiles` (A-43). */
   ownWsOutputFiles?: string[] | undefined
-  /** A sandboxed task's reach: a symlinked output it could not read is refused (`sandboxReadable`). */
-  readable?: ((real: string) => boolean) | undefined
   /** The Tier-3 input fingerprint rows captured by the pre-exec describe. */
   captured: readonly TaskInputComponent[]
   command: string
@@ -129,7 +130,7 @@ export interface SaveMissArgs {
    * (a same-project downstream task reads both), and the pack + write +
    * index go to the run's save lane (save-lane.ts).
    */
-  deferSave?: ((save: () => Promise<void>) => Promise<void>) | undefined
+  deferSave?: ((save: () => Promise<void>) => Promise<boolean>) | undefined
   /** Time the save and size its artifact, for a telemetry sink: one stat. */
   measure?: boolean | undefined
 }
@@ -138,6 +139,8 @@ export interface SaveMissArgs {
 export interface SaveFacts {
   saveMs?: number
   artifactBytes?: number
+  /** The entry landed: the outcome's `saved`, set only once it has. */
+  saved?: true
 }
 
 /**
@@ -147,13 +150,16 @@ export interface SaveFacts {
 export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveFacts> }> {
   const { node, cache, log } = a
   const endResolve = span('miss: resolve outputs')
-  const outputFiles =
-    a.ownOutputFiles ??
-    (await resolveOutputs({
-      projectDir: node.projectDir,
-      outputs: a.outputs,
-      nestedProjectDirs: a.nestedProjectDirs,
-    }))
+  // An additive task owns only the files it wrote (item 588), no directory.
+  const tree =
+    a.ownOutputFiles !== undefined
+      ? { files: a.ownOutputFiles, emptyDirs: [] }
+      : await resolveOutputTree({
+          projectDir: node.projectDir,
+          outputs: a.outputs,
+          nestedProjectDirs: a.nestedProjectDirs,
+        })
+  const outputFiles = tree.files
   const wsOutputFiles =
     a.ownWsOutputFiles ??
     (await resolveWorkspaceOutputs({
@@ -204,11 +210,11 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
       hash: a.hash,
       projectDir: node.projectDir,
       outputFiles,
-      ...(wsOutputFiles.length > 0
-        ? { workspaceOutputFiles: wsOutputFiles, workspaceRoot: a.workspaceRoot }
-        : {}),
+      ...(tree.emptyDirs.length > 0 ? { outputDirs: tree.emptyDirs } : {}),
+      // The root an output symlink's target must stay inside, outputs.workspaceFiles or not.
+      workspaceRoot: a.workspaceRoot,
+      ...(wsOutputFiles.length > 0 ? { workspaceOutputFiles: wsOutputFiles } : {}),
       inputComponents: a.captured.map((c) => ({ entryHash: a.hash, ...c })),
-      readable: a.readable,
       // No `exitCode`: the save only runs under `effectiveExitCode === 0`, and
       // the contract no longer accepts one — so the invariant is enforced by
       // the type rather than by every call site remembering the gate.
@@ -258,9 +264,13 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
   // Off the slot when the run keeps a lane (the save lane bounds and
   // drains it); in the slot otherwise — an embedder without a lane gets
   // the entry before the outcome.
-  if (a.deferSave !== undefined) return { landed: a.deferSave(save).then(() => facts) }
+  if (a.deferSave !== undefined) {
+    return {
+      landed: a.deferSave(save).then((stored) => (stored ? { ...facts, saved: true } : facts)),
+    }
+  }
   await save()
-  return { landed: Promise.resolve(facts) }
+  return { landed: Promise.resolve({ ...facts, saved: true }) }
 }
 
 /** What `markUnsaved` reads of a miss: where its declared outputs are. */

package/src/orchestrator/options.ts

@@ -90,8 +90,16 @@ export interface RunOptions {
    * saying it is not.
    */
   remoteRequested?: boolean
-  /** This run's `cache.scope` (the CLI's `--cache-scope`), above `VX_CACHE_SCOPE` and `.vx/workspace`. */
+  /** This run's cache scope, above `VX_CACHE_SCOPE`, a plugin's and the branch's (an embedder's). */
   cacheScope?: string
+  /**
+   * What the branch changed, for a scoped run: the tasks whose key it can
+   * move read the scope's key, every other task the default key (one
+   * lookup each). Absent, the run diffs the branch from `scopeBase`.
+   */
+  scopeChanges?: AffectedChanges
+  /** The commit a scoped run diffs the branch from (`--affected`'s base); absent, a plugin's, else the merge base with the default branch. */
+  scopeBase?: string
   /**
    * The default policy's remote write is off (`remote:r`): the CLI passes it
    * off CI (`CI` unset, `0` or `false`) unless `--cache-policy` or

package/src/orchestrator/output-host.ts

@@ -7,7 +7,15 @@ import type { Logger } from '../report/index.js'
 import type { OutputContext, VxPlugin } from './plugin.js'
 
 const REQUIRED = ['status', 'taskStdout', 'taskStderr', 'taskComplete'] as const
-const OPTIONAL = ['runStart', 'taskStart', 'runEnd', 'stepStart', 'stepEnd', 'runDone'] as const
+const OPTIONAL = [
+  'runStart',
+  'taskStart',
+  'runEnd',
+  'stepStart',
+  'stepEnd',
+  'runStop',
+  'runDone',
+] as const
 
 /** Reject anything that is not Logger-shaped, naming what is missing. */
 function checkLogger(value: unknown): Logger {

package/src/orchestrator/plan.ts

@@ -146,6 +146,10 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
   const outcomes = await runGraph({
     nodes: args.nodes,
     concurrency: 1,
+    // A plan's keys and probes do not depend on the order it walks in, so
+    // it ranks nothing: the default ranking's closure over every task was
+    // ~30 ms of a 1,000-project `--dry`.
+    strategy: 'ready-order',
     execute: async (node, live) => {
       const upstream = keyUpstream(node, live)
       const hashArgs = {

package/src/orchestrator/plugin-host.ts

@@ -9,6 +9,7 @@
 
 import path from 'node:path'
 import {
+  type BranchScope,
   type Cache,
   type CacheLayer,
   type CachePolicy,
@@ -34,7 +35,7 @@ import type {
   RunReport,
   ScheduleHookContext,
   VxPlugin,
-  WorkspaceHookContext,
+  ConfigContext,
 } from './plugin.js'
 import type { ProjectMeta } from '../workspace/index.js'
 
@@ -137,7 +138,7 @@ function assertEditedInPlace(
 export async function applyConfigHooks(
   plugins: readonly VxPlugin[],
   workspace: WorkspaceConfig,
-  ctx: WorkspaceHookContext,
+  ctx: ConfigContext,
   /** Runs after EACH plugin's edit, so a refusal can name the plugin that made it. */
   afterEach?: (plugin: VxPlugin) => void,
 ): Promise<void> {
@@ -381,6 +382,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>
@@ -525,6 +556,8 @@ export interface CacheHost extends CacheContext {
   readonly policy: CachePolicy
   /** Filled with each remote and what its policy lets it do, for the plugins' `ctx.cache`. */
   readonly remotes?: ResolvedRemote[]
+  /** The run's branch scope, which picks each remote key. */
+  readonly branch?: BranchScope
 }
 
 /**
@@ -539,7 +572,7 @@ export async function resolveCache(
   plugins: readonly VxPlugin[],
   host: CacheHost,
 ): Promise<CacheLayer> {
-  const { localCache, policy, remotes, ...ctx } = host
+  const { localCache, policy, remotes, branch, ...ctx } = host
   const resolved: ResolvedRemote[] = []
   for (const plugin of plugins) {
     if (plugin.cache === undefined) continue
@@ -548,6 +581,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}`),
@@ -555,7 +589,7 @@ export async function resolveCache(
     resolved.push(entry)
     remotes?.push(entry)
   }
-  return resolved.length === 0 ? localCache : new LayeredCache(localCache, resolved)
+  return resolved.length === 0 ? localCache : new LayeredCache(localCache, resolved, branch)
 }
 
 /** The plugin each resolved executor came from, so a hook of it that throws is named. */

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'
@@ -61,8 +61,10 @@ export interface VxPlugin {
    * The workspace config, before anything is derived from it (concurrency,
    * cacheDir, timeout, …). `plugins` is already fixed by the time this runs.
    * Core re-validates after each plugin, as it does a user's file.
+   * `ctx.setBranch` names what the CI knows of the branch: its cache scope
+   * and the commit it is compared with.
    */
-  config?(workspace: WorkspaceConfig, ctx: WorkspaceHookContext): void | Promise<void>
+  config?(workspace: WorkspaceConfig, ctx: ConfigContext): void | Promise<void>
 
   /**
    * Projects beyond the directories holding a vx.config, their names, and
@@ -285,8 +287,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). */
@@ -336,6 +342,22 @@ export interface WorkspaceHookContext {
   warn(message: string): void
 }
 
+/**
+ * What a CI knows of the run's branch (owner, 2026-10-17): `scope`, the
+ * cache scope (`'vznjs/vx:feat-x'`; `VX_CACHE_SCOPE` beats it, and it
+ * beats the one git names), and `base`, the commit the branch is compared
+ * with (a pull request's base), for a bare `--affected` and for which
+ * tasks read the scope. A later plugin's field wins.
+ */
+export interface BranchFacts {
+  scope?: string
+  base?: string
+}
+
+export interface ConfigContext extends WorkspaceHookContext {
+  setBranch(facts: BranchFacts): void
+}
+
 export interface DiscoverContext extends WorkspaceHookContext {
   /** Where vx's cache lives: a plugin may keep what it read to answer here. */
   readonly cacheDir: string
@@ -419,6 +441,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 +457,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 {
@@ -463,7 +503,7 @@ export interface ScheduleHookContext extends BaseContext {
 /** A `cache` hook's context: the workspace and the run's scope, never the local store or the policy, which core owns. */
 export interface CacheContext extends BaseContext {
   /**
-   * The run's `cache.scope` (`'pr-123'`), `undefined` when none. Core already keys a scoped run's
+   * The run's cache scope (`'vznjs/vx:feat-x'`), `undefined` when none. Core already keys a scoped run's
    * writes apart; a remote reads it to pick a credential or check a token's
    * claims (an OIDC branch) for every call it makes.
    */
@@ -695,6 +735,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 +768,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 +797,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