@vzn/vx 0.0.641 → 0.0.643

package/src/cli/select.ts

@@ -12,6 +12,7 @@ import {
   refIsHead,
   applyFilters,
   buildPackageGraph,
+  configuredBaseBranch,
   defaultAffectedBase,
   findWorkspaceRoot,
   type FingerprintClaims,
@@ -36,6 +37,7 @@ import {
 } from '../util/index.js'
 import {
   claimedAffected,
+  claimedExtraFiles,
   fingerprintClaims,
   gitOfDiscovery,
   hasHook,
@@ -48,7 +50,6 @@ import {
   loadCliProjects,
   loadCliWorkspace,
 } from './workspace-config.js'
-import { resolveSetting } from '../settings.js'
 
 /**
  * The projects whose tasks declare an `inputs.workspaceFiles` glob
@@ -123,6 +124,7 @@ async function workspaceFingerprintClaims(
   return {
     files: new Set(claims.keys()),
     affected: (change) => claimedAffected(claims.get(change.file)!, change, ctx),
+    extraFiles: (file, bytes) => claimedExtraFiles(claims.get(file)!, file, bytes),
   }
 }
 
@@ -242,20 +244,18 @@ function refusalOf(err: unknown): Refusal {
 
 /**
  * The filter `--affected[=<base>]` stands for: `...[<base>]`, the changed
- * projects and their dependents. An empty base is `run.affectedBase`
- * (its variable, then the workspace's, which a plugin's `config` stage may set from nx.json's
- * `defaultBase` or `TURBO_SCM_BASE`), then the guess.
+ * projects and their dependents. An empty base is a plugin's (`setBranch`:
+ * a pull request's base commit), else the merge base with `baseBranch`.
  */
 export async function affectedFilterFor(cwd: string, affected: string): Promise<string | Refusal> {
   const root = await findWorkspaceRoot(cwd)
   let base = affected
   if (base === '') {
-    const ws = (await loadCliWorkspace(root)).workspaceConfig
-    base = (resolveSetting('run.affectedBase', ws).value as string | undefined) ?? ''
-  }
-  if (base === '') {
+    const ws = await loadCliWorkspace(root)
     try {
-      base = await defaultAffectedBase(root)
+      base =
+        ws.branch.base ??
+        (await defaultAffectedBase(root, configuredBaseBranch(ws.workspaceConfig)))
     } catch (err) {
       if (!isUserError(err)) throw err
       return refusalOf(err)

package/src/cli/workspace-config.ts

@@ -15,7 +15,7 @@ import {
   lockOfDiscovery,
   lockReader,
 } from '../orchestrator/index.js'
-import type { VxPlugin } from '../orchestrator/index.js'
+import type { BranchFacts, VxPlugin } from '../orchestrator/index.js'
 import {
   buildPackageGraph,
   type ProjectEntry,
@@ -27,6 +27,8 @@ import {
 interface CliWorkspace {
   workspaceConfig: WorkspaceConfig | null
   plugins: readonly VxPlugin[]
+  /** What a plugin's `config` stage said of the branch: its cache scope and base commit. */
+  branch: BranchFacts
   cacheDir: string
   /** The shared store a run opens `cacheDir` with (`resolveStoreRoot`), asked on load. */
   storeRoot: Promise<string | null>
@@ -37,10 +39,14 @@ export const warnToStderr = (message: string): void => {
 }
 
 export async function loadCliWorkspace(workspaceRoot: string): Promise<CliWorkspace> {
-  const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, warnToStderr)
+  const { workspaceConfig, plugins, branch } = await loadWorkspacePlugins(
+    workspaceRoot,
+    warnToStderr,
+  )
   return {
     workspaceConfig,
     plugins,
+    branch,
     cacheDir: resolveCacheDir(workspaceRoot, workspaceConfig),
     storeRoot: resolveStoreRoot(workspaceRoot, workspaceConfig),
   }

package/src/config.ts

@@ -14,6 +14,13 @@ export type Duration = `${number}${'ms' | 's' | 'm' | 'h' | 'd'}`
  * Nothing here is folded into a cache key.
  */
 export interface WorkspaceConfig {
+  /**
+   * The repository's default branch (`'develop'`). A run on it has no
+   * cache scope and a bare `--affected` has no default; elsewhere both
+   * compare with the merge base of `origin/<baseBranch>` and HEAD.
+   * Omitted → `origin/HEAD`'s branch, then `main`, then `master`.
+   */
+  baseBranch?: string
   run?: RunSettings
   cache?: CacheSettings
   lock?: LockSettings
@@ -42,13 +49,6 @@ export interface RunSettings {
    * `schedule` plugin's weights still come first; this breaks their ties.
    */
   schedule?: 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
-  /**
-   * The git ref a bare `--affected` compares with (`origin/develop`).
-   * `--affected=<base>` overrides it. Omitted → `origin/HEAD`, then the
-   * first of `origin/main`, `origin/master`, `main`, `master` that is not
-   * HEAD, else `HEAD~1`.
-   */
-  affectedBase?: string
   /**
    * A task's time limit, for tasks without their own `exec.timeout` (which
    * beats every run-level source). A runaway-process guard: a timed-out
@@ -95,15 +95,6 @@ export interface CacheSettings {
    * first, then each remote in declared order.
    */
   policy?: string
-  /**
-   * Where this run's cache writes land. Omitted, a run reads and writes the
-   * default keys. A name (`'pr-123'`) reads the default key first, then the
-   * scope's, and writes only the scope's, so a PR never writes what the
-   * default branch reads. Whether a run writes at all is `policy`'s call.
-   * A client-side convention, not a security boundary: the boundary is a
-   * cache token the server limits.
-   */
-  scope?: string
   /** Which remote hits land on disk: `all` (the default), only the requested tasks' (`toplevel`), or `none`. */
   download?: 'all' | 'toplevel' | 'none'
   /** The `cache.inputStability` of every task that does not set its own. */

package/src/exec/runner.ts

@@ -50,6 +50,10 @@ export interface RunResult {
   /** `Bun.spawn` threw: no shell ran, so its 127 is vx's and says nothing
    *  about the command (A-41). */
   spawnFailed?: true
+  /** The shell exited while a process it started still held its
+   *  stdout/stderr past the drain bound (`POST_EXIT_CUT_LINE`): that process
+   *  may still write the task's outputs, so the result is not saved. */
+  leftRunning?: true
 }
 
 /**
@@ -1034,6 +1038,7 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
     stderr,
     ...(proc.signalCode ? { signal: proc.signalCode } : {}),
     ...(timeout.timedOut() ? { timedOut: true } : {}),
+    ...(cut ? { leftRunning: true } : {}),
     ...resourceUsageToCpuRss(proc.resourceUsage(), rssFloorFor),
   }
 }

package/src/exec/sandbox-runtime.ts

@@ -1344,7 +1344,7 @@ async function wrapIn(
   if (process.platform === 'darwin') {
     const rules = [
       ...macProfileRules(args.config),
-      ...darwinWallRules(args.config, baselines.allowRead),
+      ...darwinGrantRules(args.config, baselines.allowRead, baselines.denyRead),
     ]
     try {
       if (rules.length > 0) wrapped = injectProfileRules(wrapped, rules)
@@ -2270,6 +2270,7 @@ async function runSandboxedOnce(
     violations,
     ...(proc.signalCode ? { signal: proc.signalCode } : {}),
     ...(timeout.timedOut() ? { timedOut: true } : {}),
+    ...(cut ? { leftRunning: true } : {}),
     // Linux: the task's CPU and peak never reach this wait. bwrap runs it
     // in a pid namespace (`--unshare-pid`), and what the namespace's
     // processes used is not folded into bwrap's usage: a 500 ms busy loop
@@ -2570,6 +2571,85 @@ export function wallsGlobsReach(grants: readonly string[], walls: readonly strin
   return walls.filter((w) => heads.some((h) => atOrUnder(w, h)))
 }
 
+/**
+ * macOS: the grant rules vx appends. The listings come first so a wall's
+ * deny, later, wins: SBPL is last-match-wins.
+ */
+export function darwinGrantRules(
+  c: Pick<ResolvedSandboxConfig, 'wallsReached' | 'allowRead' | 'allowWrite'>,
+  baseAllowRead: readonly string[],
+  anchors: readonly string[],
+): string[] {
+  return [...darwinAncestorRules(c, anchors), ...darwinWallRules(c, baseAllowRead)]
+}
+
+/**
+ * macOS: each directory above a grant may be listed, as on Linux. bwrap
+ * makes every directory above a mount, so a task granted
+ * `../vx-*\/package.json` could glob it from `..`; seatbelt matches paths
+ * and refused the listing (EPERM), so `@vzn/vx-docs#import` failed on
+ * every Mac (2026-10-17). Above the glob that is each literal directory
+ * strictly inside a deny anchor (outside one, all is readable already);
+ * a directory the glob itself names (`vx-a/`) is matched as a regex, and
+ * under a `**` any directory is. The rules grant directories only, never
+ * a file, and come before the wall denies, which still win.
+ *
+ * A listing shows every name in the directory, where Linux's scaffold
+ * shows only what it mounted: names, never a file's data. Not the anchor
+ * itself: Bun, shown the workspace root's `package.json` it
+ * may not read, failed with "Cannot read file" (EPERM).
+ */
+export function darwinAncestorRules(
+  c: Pick<ResolvedSandboxConfig, 'allowRead' | 'allowWrite'>,
+  anchors: readonly string[],
+): string[] {
+  const literals = new Set<string>()
+  const patterns = new Set<string>()
+  // Grants are canonical already (`resolveSandboxConfig`), and so is each
+  // directory above one: no realpath here, at every spawn.
+  const inside = (d: string): boolean => anchors.some((a) => d !== a && atOrUnder(d, a))
+  for (const g of [...c.allowRead, ...c.allowWrite]) {
+    const named = namedPath(g)
+    const head = g.slice(0, g.search(MOUNT_WILDCARDS))
+    const cut = head.lastIndexOf('/')
+    const top = named !== undefined ? path.dirname(named) : head.slice(0, cut) || '/'
+    for (let d = top; inside(d); d = path.dirname(d)) literals.add(d)
+    if (named !== undefined || g.includes('\\')) continue
+    let re = top === '/' ? '' : regexLiteral(top)
+    for (const part of g
+      .slice(cut + 1)
+      .split('/')
+      .slice(0, -1)) {
+      if (part === '**') {
+        patterns.add(`^${re}(/.*)?$`)
+        break
+      }
+      re += `/${part
+        .replace(/[.^$+{}()|]/g, '[$&]')
+        .replaceAll('*', '[^/]*')
+        .replaceAll('?', '[^/]')}`
+      patterns.add(`^${re}$`)
+    }
+  }
+  // A name seatbelt's quoted string cannot hold keeps today's refusal
+  // rather than failing the task (`sbplResolvedPath` would throw).
+  const spellable = (p: string): boolean => !UNSPELLABLE.test(p)
+  return [
+    ...[...literals].filter(spellable).map((d) => `(allow file-read-data (literal "${d}"))`),
+    ...[...patterns]
+      .filter(spellable)
+      .map((r) => `(allow file-read-data (require-all (vnode-type DIRECTORY) (regex #"${r}")))`),
+  ]
+}
+
+// eslint-disable-next-line no-control-regex -- the control range is the point
+const UNSPELLABLE = /["'\\\x00-\x1f\x7f]/
+
+/** A real path as a regex matching only itself: each special in a class of one. */
+function regexLiteral(p: string): string {
+  return p.replace(/[.^$+{}()|*?[\]]/g, (ch) => `[${ch}]`)
+}
+
 /**
  * macOS: the walls a glob grant reaches, denied at the profile's tail
  * (SBPL is last-match-wins). SRT re-emits a wall's deny after the allows

package/src/graph/priorities.ts

@@ -23,7 +23,20 @@ export function tieredReverseDepCount(
   restoreTier: ReadonlySet<string>,
 ): Map<string, number> {
   const exec = new Map<string, TaskNode>()
-  for (const [id, node] of nodes) if (!restoreTier.has(id)) exec.set(id, node)
+  let runsAny = false
+  for (const [id, node] of nodes) {
+    if (restoreTier.has(id)) continue
+    exec.set(id, node)
+    if (node.config.exec !== undefined) runsAny = true
+  }
+  // Nothing outside the restore tier runs a command (a warm run: restores
+  // and groups), so no order finishes any work sooner: everything ranks 0.
+  // The weights below were 10 ms of a 1,000-project warm run.
+  if (!runsAny) {
+    const zeros = new Map<string, number>()
+    for (const id of nodes.keys()) zeros.set(id, 0)
+    return zeros
+  }
   // An exec tier with no edge inside it (a warm run's groups) counts 0
   // everywhere: no closure to build.
   let linked = false

package/src/history/history.ts

@@ -263,56 +263,66 @@ export class LocalHistoryProvider implements HistoryProvider {
    * newest imported timing (`importTimings`), else the median on any
    * branch, else none. The timings are the shared store's `task_durations`, so every
    * worktree of the repo reads them and a new one forecasts on its first
-   * run. A point read per task on `(project, task, source, id)`: exact
-   * however old the rows, where the runs window holds only the newest
-   * invocations.
+   * run. One statement per tier, an index probe per task on `(project,
+   * task, source, id)` inside it: exact however old the rows, where the
+   * runs window holds only the newest invocations.
    */
   private forecasts(wanted: ReadonlySet<string>): Map<string, number> {
     const out = new Map<string, number>()
     this.lackedBranchHistory = false
     if (wanted.size === 0) return out
-    // Tiers, first answer wins.
-    type Tier = (project: string, task: string) => Array<{ ms: number }>
+    // Tiers, first answer wins: a WHERE over `task_durations`, its params,
+    // and how many of the newest rows it reads.
+    type Tier = { where: string; params: string[]; limit: number }
     const tiers: Tier[] = []
-    const newest = (where: string) =>
-      this.db.query(
-        `SELECT duration_ms AS ms FROM task_durations WHERE project = ? AND task = ? AND ${where}
-         ORDER BY id DESC LIMIT ${FORECAST_RUNS}`,
-      )
     if (this.branch !== undefined) {
-      const source = branchSource(this.branch)
-      const q = newest('source = ?')
-      tiers.push((p, t) => q.all(p, t, source) as Array<{ ms: number }>)
+      tiers.push({ where: 'source = ?', params: [branchSource(this.branch)], limit: FORECAST_RUNS })
     }
     // One probe on the partial index first: a store with no import costs
-    // no query per task.
+    // no tier.
     if (
       this.db.query(`SELECT 1 FROM task_durations WHERE source = 'remote' LIMIT 1`).get() !== null
     ) {
-      const remote = this.db.query(
-        `SELECT duration_ms AS ms FROM task_durations WHERE project = ? AND task = ? AND source = 'remote'
-         ORDER BY id DESC LIMIT 1`,
-      )
-      tiers.push((p, t) => remote.all(p, t) as Array<{ ms: number }>)
+      tiers.push({ where: `source = 'remote'`, params: [], limit: 1 })
     }
-    const any = newest(`source LIKE 'branch:%'`)
-    tiers.push((p, t) => any.all(p, t) as Array<{ ms: number }>)
+    tiers.push({ where: `source LIKE 'branch:%'`, params: [], limit: FORECAST_RUNS })
     const own = this.branch !== undefined ? tiers[0] : tiers.at(-1)
-    let lacked = false
-    for (const id of wanted) {
-      const [project, task] = splitTaskId(id)
-      let answered: Tier | undefined
-      for (const tier of tiers) {
-        const rows = tier(project, task)
-        if (rows.length === 0) continue
-        const durations = rows.map((r) => r.ms).sort((x, y) => x - y)
+    let pending = [...wanted]
+    let ownAnswered = 0
+    for (const tier of tiers) {
+      if (pending.length === 0) break
+      // One statement per tier over every task it is asked for: an index
+      // probe per task inside SQLite, where a query per task from here was
+      // 31-40 ms of 2,000 tasks against 5-8.
+      const rows = this.db
+        .query(
+          `SELECT j.key AS i, (SELECT group_concat(ms) FROM (
+             SELECT duration_ms AS ms FROM task_durations
+             WHERE project = j.value ->> 0 AND task = j.value ->> 1 AND ${tier.where}
+             ORDER BY id DESC LIMIT ${tier.limit})) AS ds
+           FROM json_each(?) AS j`,
+        )
+        .all(...tier.params, JSON.stringify(pending.map(splitTaskId))) as {
+        i: number
+        ds: string | null
+      }[]
+      const left: string[] = []
+      for (const r of rows) {
+        const id = pending[r.i]!
+        if (r.ds === null) {
+          left.push(id)
+          continue
+        }
+        const durations = r.ds
+          .split(',')
+          .map(Number)
+          .sort((x, y) => x - y)
         out.set(id, pickPercentile(durations, 0.5))
-        answered = tier
-        break
+        if (tier === own) ownAnswered++
       }
-      if (answered !== own) lacked = true
+      pending = left
     }
-    this.lackedBranchHistory = lacked
+    this.lackedBranchHistory = ownAnswered < wanted.size
     return out
   }
 

package/src/index.ts

@@ -46,6 +46,7 @@ export type {
 } from './config.js'
 export { defineProject, defineWorkspace } from './config.js'
 export { definePlugin, refuseUnknownOptions } from './orchestrator/index.js'
+export { branchCacheScope } from './workspace/index.js'
 
 // Programmatic engine API: run / plan / prepare (docs/cli.md § Programmatic
 // API). The graph primitives, the cache-key hashing seam and the git / host
@@ -83,9 +84,20 @@ export type {
   CacheLayer,
   PluginCache,
   RemoteCacheLayer,
+  RemoteKey,
+  RemoteOpenContext,
   RunRecord,
   InvocationRecord,
 } from './cache/index.js'
+// A plugin's keychain (`ctx.secret` on `setup` and a remote's `open`), and
+// the guard that tells a missing secret from a fault.
+export { isSecretUnavailable } from './util/index.js'
+export type {
+  PluginSecrets,
+  SecretRequest,
+  SecretUnavailable,
+  SecretUnavailableReason,
+} from './util/index.js'
 
 // Workspace discovery + the project/config catalog surface — an
 // out-of-process service/CLI needs these. `loadProjectConfig` is the RAW
@@ -161,6 +173,8 @@ export type {
   ScheduleHookContext,
   AdmitContext,
   WorkspaceHookContext,
+  ConfigContext,
+  BranchFacts,
   DiscoverContext,
   DiscoveredProject,
   PluginSetupContext,

package/src/orchestrator/affected-tasks.ts

@@ -41,6 +41,7 @@ const KEYED_BY_EVERY_TASK: ReadonlySet<string> = new Set(PROJECT_CONFIG_FILENAME
 function wholeProjects(
   changes: AffectedChanges,
   projects: ReadonlyMap<string, ProjectEntry>,
+  byKeys: boolean,
 ): Map<string, string | undefined> {
   // Each whole project, with the path no task claims when one did it.
   const whole = new Map<string, string | undefined>([...changes.whole].map((n) => [n, undefined]))
@@ -50,7 +51,7 @@ function wholeProjects(
       (t) => t.exec !== undefined && t.inputs !== undefined,
     )
     const unclaimed = (rel: string): boolean =>
-      KEYED_BY_EVERY_TASK.has(rel) || !keyed.some((t) => declaresInput(t, rel, null))
+      KEYED_BY_EVERY_TASK.has(rel) || (!byKeys && !keyed.some((t) => declaresInput(t, rel, null)))
     const rel = rels.find(unclaimed)
     if (rel !== undefined) whole.set(name, rel)
   }
@@ -99,8 +100,10 @@ export function affectedRoots(
   projects: ReadonlyMap<string, ProjectEntry>,
   packageGraph: PackageGraph,
   explain?: AffectedExplain,
+  /** Only what moves a key: a changed path no task declares reaches no task. */
+  byKeys = false,
 ): string[] {
-  const whole = wholeProjects(changes, projects)
+  const whole = wholeProjects(changes, projects, byKeys)
   const seeds = explain === undefined ? null : new Map<string, AffectedReason>()
   const through = explain === undefined ? null : new Map<string, string>()
   const inProject = (name: string, rel: string | undefined): AffectedReason => {
@@ -226,6 +229,24 @@ export function affectedRoots(
   return kept
 }
 
+/**
+ * The tasks of `nodes` whose key the change can move (a branch's cache
+ * scope, owner 2026-10-17): a changed path one of its inputs declares, a
+ * whole project, or a task its closure holds. Unlike `--affected`, a path
+ * no task declares (a README) reaches none: its key is the default
+ * branch's, so it reads the default key.
+ */
+export function keyedByChange(
+  nodes: ReadonlyMap<string, TaskNode>,
+  changes: AffectedChanges,
+  projects: ReadonlyMap<string, ProjectEntry>,
+  packageGraph: PackageGraph,
+): Set<string> {
+  return new Set(
+    affectedRoots(nodes, [...nodes.keys()], changes, projects, packageGraph, undefined, true),
+  )
+}
+
 /**
  * The requested tasks `--affected` keeps, in their order: one the user
  * named (`pkg#task`), one in a project another include selected outright

package/src/orchestrator/deferred-outputs.ts

@@ -15,7 +15,7 @@
 import {
   cleanOutputs,
   committedFiles,
-  resolveOutputs,
+  resolveOutputTree,
   type CacheLayer,
   type GitFilesCache,
 } from '../cache/index.js'
@@ -144,7 +144,7 @@ export class DeferredOutputs {
         `could not fetch deferred outputs of ${taskId}: ${msg} — re-run it with --force, or use --cache-download=all`,
       )
     }
-    const outputFiles = await resolveOutputs(cleanArgs)
+    const { files: outputFiles, emptyDirs } = await resolveOutputTree(cleanArgs)
     this.args.gitFilesCache?.markOutputsChanged(
       producer.projectDir,
       outputFiles.map((f) => f.slice(producer.projectDir.length + 1)),
@@ -157,6 +157,7 @@ export class DeferredOutputs {
         hash: entry.hash,
         projectDir: producer.projectDir,
         outputFiles,
+        ...(emptyDirs.length > 0 ? { outputDirs: emptyDirs } : {}),
         entry: entry.entry,
       })
     }

package/src/orchestrator/execute-task.ts

@@ -61,7 +61,6 @@ import {
   type Placeholder,
   reachedWithheld,
   sandboxRequestFor,
-  sandboxReadable,
   sweepPlaceholders,
   undeclaredWriteReach,
   untouchedPlaceholderLine,
@@ -233,7 +232,7 @@ export interface ExecuteArgs {
    */
   outputDirSnapshots?: OutputDirSnapshot[]
   /** The run's save lane: a miss's cache save runs off the execution slot (save-lane.ts). */
-  deferSave?: (save: () => Promise<void>) => Promise<void>
+  deferSave?: (save: () => Promise<void>) => Promise<boolean>
   /**
    * Where a deferred save's `landed` promise is parked by task id, for the
    * in-flight join (admission.ts): a duplicate of this task in another run
@@ -1278,6 +1277,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   } else if (
     effectiveExitCode === 0 &&
     willSave &&
+    nothingLeftRunning() &&
     (await keyStillTrue()) &&
     (own = await ownOutputs()) !== undefined
   ) {
@@ -1302,19 +1302,11 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       deferSave: args.deferSave,
       // A sink listens: say what the save cost.
       measure: args.explainMiss !== undefined,
-      ...(userSandbox
-        ? {
-            readable: sandboxReadable(
-              node,
-              cfg.exec!.sandbox!,
-              args.workspaceRoot,
-              args.nestedProjectDirs,
-            ),
-          }
-        : {}),
     })
-    args.deferredSaves?.set(node.id, landed)
-    saved = true
+    // A run that settles the outcome on `landed` learns there whether the
+    // entry is in; without one, the save is taken as done.
+    if (args.deferredSaves !== undefined) args.deferredSaves.set(node.id, landed)
+    else saved = true
   } else if (cfgCacheable && !remoteOnly && !deferralRequested && args.noDependants !== true) {
     // Ran here and saves nothing — failed, a read-only policy, a tainted
     // upstream, a key that no longer held — yet it wrote what a save would
@@ -1362,6 +1354,20 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     return mine
   }
 
+  /**
+   * A process the shell left behind still held its output when the drain
+   * bound cut it, so it may still write outputs: a save now would file a
+   * tree the run does not leave, and a hit elsewhere would replay it.
+   */
+  function nothingLeftRunning(): boolean {
+    if (result.leftRunning !== true) return true
+    warnOf(log)(
+      `[vx] ${node.id}: a process it left running may still write its outputs — ` +
+        `the result stands, but is not saved; wait for it in the command (\`wait\`)`,
+    )
+    return false
+  }
+
   /**
    * The input that no longer holds what the key folded, or one the key did
    * not fold that is there now: `null` when the key re-derived just before

package/src/orchestrator/hit-restore.ts

@@ -8,6 +8,7 @@
 // which bytes a green run replays. Moved out of execute-task.ts
 // 2026-09-10 as pure code motion, the mirror of miss-save.ts.
 
+import path from 'node:path'
 import type { CacheConfig } from '../config.js'
 import {
   type CacheEntry,
@@ -166,7 +167,7 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
           actual: readonly string[],
           exp: ReadonlyArray<{ path: string }>,
         ): boolean => {
-          const expSet = new Set(exp.map((e) => e.path))
+          const expSet = new Set(exp.map((e) => e.path).filter((p) => !p.endsWith('/')))
           return actual.length === expSet.size && actual.every((r) => expSet.has(r))
         }
         // A stray a dependant's glob could have added is not a stray; a path
@@ -185,7 +186,7 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
           exp: ReadonlyArray<{ path: string }>,
         ): boolean => {
           const have = new Set(actual)
-          return exp.every((e) => have.has(e.path))
+          return exp.every((e) => e.path.endsWith('/') || have.has(e.path))
         }
         treeMatches = additive
           ? rowsPresent(actualRels, projExpected) && rowsPresent(actualWsRels, wsExpected)
@@ -289,6 +290,13 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
         rels: staleRels,
         outputs,
         committed: cleanArgs.committed,
+        // A stale file in an output directory the entry holds empty takes
+        // only itself: the directory stays, as the miss left it.
+        keep: new Set(
+          heldRels
+            .filter((r) => r.endsWith('/'))
+            .map((r) => path.join(node.projectDir, r.slice(0, -1))),
+        ),
       })
     }
     if (staleWsRels.length > 0) {

package/src/orchestrator/index.ts

@@ -50,6 +50,8 @@ export {
   type ScheduleHookContext,
   type AdmitContext,
   type WorkspaceHookContext,
+  type ConfigContext,
+  type BranchFacts,
   type DiscoverContext,
   type DiscoveredProject,
   type InstallPluginsArgs,
@@ -77,6 +79,7 @@ export {
   applyProjectHooks,
   applyScheduleHooks,
   claimedAffected,
+  claimedExtraFiles,
   fingerprintClaims,
   hasHook,
   REMOTE_CACHE_METHODS,
@@ -116,6 +119,8 @@ export {
   captureWorkspaceIdentity,
   currentBranch,
   detectCi,
+  localBranchScope,
+  resolveCacheScope,
 } from './run-context.js'
 export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './run-context.js'
 export {