@vzn/vx 0.0.21 → 0.0.22

package/src/orchestrator/sandbox-request.ts

@@ -3,18 +3,26 @@
 // (bwrap cannot bind a path that does not exist). Shared by the cached path
 // (through the executor) and the persistent path (spawned in execute-task).
 
-import { mkdir, readdir, realpath, stat } from 'node:fs/promises'
+import { lstat, mkdir, readdir, realpath, rm, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import path from 'node:path'
 import type { ExecConfig } from '../config.js'
 import {
+  bindableWrites,
   initSandbox,
   probeSandbox,
+  punchWalls,
   resolveSandboxConfig,
+  type ResolvedSandboxConfig,
+  thrownReason,
+  toRealPath,
   type ExecuteRequest,
+  isMountableLiteral,
+  type SandboxViolation,
 } from '../exec/index.js'
 import type { TaskNode } from '../graph/index.js'
-import { staticPrefix, UserError } from '../util/index.js'
+import { grantPrefix, UserError } from '../util/index.js'
+import { WORKSPACE_FINGERPRINT_FILES } from '../workspace/index.js'
 
 /**
  * Arm the sandbox runtime for a run, lazily: only when at least one task
@@ -35,6 +43,46 @@ export interface SandboxArmer {
   readonly armed: boolean
 }
 
+/**
+ * What SRT's run-wide `initialize()` is armed with, folded from every
+ * sandboxed task in the graph — or `null` when the run has none.
+ *
+ * Split out of `prepareSandbox` (pure motion) because it is the only
+ * part of the arming that can be READ without starting a sandbox: the
+ * call itself is observable solely through a live runtime, so the values
+ * it carries had no witness of any kind and three separate widenings of
+ * them survived a whole-suite mutation sweep (item 537).
+ */
+export interface SandboxRunUnion {
+  /** Domains the run's filtering proxy will accept, in declaration order. */
+  domains: string[]
+  /** Whether SRT's all-or-nothing `socket(AF_UNIX)` filter is lifted for the run. */
+  unixSockets: boolean
+  /** Whether EVERY sandboxed task accepts the weaker nested profile. */
+  weakerNested: boolean
+}
+
+export function sandboxRunUnion(nodes: Iterable<TaskNode>): SandboxRunUnion | null {
+  const sandboxed = [...nodes].filter((n) => n.config.exec?.sandbox !== undefined)
+  if (sandboxed.length === 0) return null
+  const weakerNested = sandboxed.every((n) => n.config.exec?.sandbox?.weakerWhenNested === true)
+  const domains = new Set<string>()
+  let unixSockets = false
+  for (const n of sandboxed) {
+    const allow = n.config.exec?.sandbox?.allow
+    const net = allow?.network
+    // `network: true` is deliberately absent from the union: it SKIPS the
+    // proxy rather than going through it, so folding it in as `*` would
+    // widen the allowlist every OTHER task in the run is filtered against.
+    if (Array.isArray(net)) for (const d of net) domains.add(d)
+    const sockets = allow?.unixSockets
+    if (sockets === true || (Array.isArray(sockets) && sockets.length > 0)) unixSockets = true
+    const lb = allow?.localBinding
+    if (Array.isArray(lb) && lb.length > 0 && process.platform === 'linux') unixSockets = true
+  }
+  return { domains: [...domains], unixSockets, weakerNested }
+}
+
 /**
  * Prepare the sandbox for a run WITHOUT starting it. Starting is
  * `arm()`, and it happens on the first task that actually executes inside
@@ -57,20 +105,9 @@ export interface SandboxArmer {
  * it for the run. macOS keeps per-task precision through vx's own rules.
  */
 export function prepareSandbox(nodes: Iterable<TaskNode>): SandboxArmer | null {
-  const sandboxed = [...nodes].filter((n) => n.config.exec?.sandbox !== undefined)
-  if (sandboxed.length === 0) return null
-  const weakerNested = sandboxed.every((n) => n.config.exec?.sandbox?.weakerWhenNested === true)
-  const domains = new Set<string>()
-  let unixSockets = false
-  for (const n of sandboxed) {
-    const allow = n.config.exec?.sandbox?.allow
-    const net = allow?.network
-    if (Array.isArray(net)) for (const d of net) domains.add(d)
-    const sockets = allow?.unixSockets
-    if (sockets === true || (Array.isArray(sockets) && sockets.length > 0)) unixSockets = true
-    const lb = allow?.localBinding
-    if (Array.isArray(lb) && lb.length > 0 && process.platform === 'linux') unixSockets = true
-  }
+  const union = sandboxRunUnion(nodes)
+  if (union === null) return null
+  const { domains, unixSockets, weakerNested } = union
   let pending: Promise<void> | undefined
   let armed = false
   return {
@@ -83,7 +120,7 @@ export function prepareSandbox(nodes: Iterable<TaskNode>): SandboxArmer | null {
           const avail = await probeSandbox({ weakerNested })
           if (!avail.available) throw new UserError(`sandbox not available: ${avail.reason}`)
           await initSandbox({
-            allowedDomains: [...domains],
+            allowedDomains: domains,
             ...(unixSockets ? { allowAllUnixSockets: true } : {}),
           })
         } catch (err) {
@@ -91,9 +128,7 @@ export function prepareSandbox(nodes: Iterable<TaskNode>): SandboxArmer | null {
           // the dependency check does not cover) gets the same one-line
           // verdict as a refused probe, not an internal error with a stack.
           if (err instanceof UserError) throw err
-          throw new UserError(
-            `sandbox not available: ${err instanceof Error ? err.message : String(err)}`,
-          )
+          throw new UserError(`sandbox not available: ${thrownReason(err)}`)
         }
         armed = true
       })()
@@ -106,25 +141,31 @@ export function prepareSandbox(nodes: Iterable<TaskNode>): SandboxArmer | null {
  * The sandbox half of an `ExecuteRequest` for one task, shared by the
  * cached path (through the executor) and the persistent path (spawned here).
  *
- * The sandbox derives NOTHING from `cache` (owner, 2026-09-05). Those are
- * two different questions: `cache.inputs` says what INVALIDATES the task,
- * `sandbox.allow` says what it may TOUCH. Deriving one from the other
+ * The user's grants derive NOTHING from `cache` (owner, 2026-09-05). Those
+ * are two different questions: `cache.inputs` says what INVALIDATES the
+ * task, `sandbox.allow` says what it may TOUCH. Deriving one from the other
  * coupled them in both directions — a declaration added for caching
  * silently widened the sandbox, and a path the task needed had to be
  * laundered through the cache key to get it. A sandboxed task declares
  * its own reads and writes.
  *
- * `node_modules` is the one grant core still makes, and it is not
- * cache-derived: it is where the task's own PATH gets its `.bin` entries,
- * and denying it made the sandbox unusable for anything that imports a
- * dependency (`bun build --compile` died with only `error: An unknown
- * error occurred (Unexpected)`; owner call 2026-09-04).
+ * `node_modules` is the one grant core still makes: it is where the task's
+ * own PATH gets its `.bin` entries, and denying it made the sandbox
+ * unusable for anything that imports a dependency (`bun build --compile`
+ * died with only `error: An unknown error occurred (Unexpected)`; owner
+ * call 2026-09-04). Declaring `cache` may NARROW that grant, never widen
+ * anyone's (2026-09-24): `keyed` is the set of project directories the
+ * task's key answers for (keyed-projects.ts), and `undefined` for a task
+ * with no `cache`, which has no key to be stale.
  */
 export async function sandboxRequestFor(
   node: TaskNode,
   sandbox: NonNullable<ExecConfig['sandbox']>,
   workspaceRoot: string,
-): Promise<NonNullable<ExecuteRequest['sandbox']>> {
+  keyed: ReadonlySet<string> | undefined,
+  /** The projects nested in this one (their dirs): a wall its grants do not reach. */
+  nested: readonly string[] = [],
+): Promise<SandboxRequest> {
   const depDirs = [
     path.join(node.projectDir, 'node_modules'),
     path.join(workspaceRoot, 'node_modules'),
@@ -133,18 +174,26 @@ export async function sandboxRequestFor(
   // sibling project, so granting `node_modules` grants a link whose
   // target is outside it. That target is a dependency, not a reach-out:
   // no project config should have to name a sibling to import what its
-  // own `package.json` depends on (owner, 2026-09-05).
-  depDirs.push(...(await linkedDeps(depDirs)))
+  // own `package.json` depends on (owner, 2026-09-05) — when the key
+  // moves with it.
+  const links = await linkedDeps(depDirs, node.projectDir, workspaceRoot, keyed)
+  depDirs.push(...links.granted)
   // bwrap cannot --bind a path that does not exist: the bind silently
   // becomes a no-op and writes to it appear to succeed but never land.
-  // Pre-create what the task said it will write.
-  await prepareOutputsForBind(node.projectDir, sandbox.allow?.write ?? [])
-  return {
+  // Pre-create what the task said it will write — after the grants are
+  // resolved, which refuses one that leaves the project through a link
+  // before anything is created along it (item 1003).
+  const config = wallOff(resolveSandboxConfig(sandbox, node.projectDir), workspaceRoot, [
+    ...nested,
+    path.join(workspaceRoot, '.git'),
+    path.join(workspaceRoot, '.vx'),
+  ])
+  const placeholders = await prepareOutputsForBind(node.projectDir, sandbox.allow?.write ?? [])
+  const request: NonNullable<ExecuteRequest['sandbox']> = {
     // Only what the task declared, plus node_modules. Write paths are
     // readable too: a task that writes `dist/x` expects to read it back
     // (`tsc --incremental` re-reads .tsbuildinfo).
     baseAllowRead: depDirs,
-    baseAllowWrite: [],
     // Enforcement anchors at the WORKSPACE ROOT: a task may not leave
     // its project, so every sibling and every root file is denied.
     // Reporting is a different question — see `reportWithin` below.
@@ -157,46 +206,171 @@ export async function sandboxRequestFor(
     // project's own files — that is the one that breaks the cache key,
     // because the key folds this project's inputs.
     reportWithin: node.projectDir,
-    config: resolveSandboxConfig(sandbox, node.projectDir),
+    // …and of a dependency withheld above: the task reached for it
+    // through its own `node_modules`, and that read is the stale hit the
+    // withholding exists to stop, not the wall.
+    reportLinked: links.withheld.map((w) => w.dir),
+    config,
   }
+  return { sandbox: request, placeholders, withheld: links.withheld }
 }
 
 /**
- * Where the workspace links in `dirs` actually point.
+ * The sandbox half of the request, plus the empty files vx created so a
+ * literal write grant had something to bind (`placeholders`). They are
+ * vx's, not the task's, until the task writes them: `sweepPlaceholders`
+ * takes back the ones it never touched. `withheld` names the linked
+ * dependencies a cached task was denied, for the hint a denial under one
+ * earns (`withheldLinkLine`).
+ */
+export interface SandboxRequest {
+  sandbox: NonNullable<ExecuteRequest['sandbox']>
+  placeholders: Placeholder[]
+  withheld: WithheldLink[]
+}
+
+/** An empty file vx created for a bind, and its mtime at creation. */
+export interface Placeholder {
+  path: string
+  mtimeMs: number
+}
+
+/** A workspace link whose target the task's key does not answer for. */
+export interface WithheldLink {
+  /** The canonical target, inside the workspace root. */
+  dir: string
+  /** The name it is installed under (`@x/ui`). */
+  name: string
+  /** The target and the link, workspace-relative POSIX, for the hint. */
+  target: string
+  link: string
+}
+
+/**
+ * Where the workspace links in `dirs` actually point, split into what the
+ * task is granted and what it is not.
  *
  * One level deep, plus one level inside a `@scope/` directory — the shape
  * a package manager writes. Anything already inside a granted directory
  * is dropped; what is left is a sibling project's real path.
+ *
+ * A link to the task's OWN project, or to a directory holding it, is
+ * dropped too: npm and Yarn classic link every workspace package at the
+ * root, the task's own included, and granting that target handed the
+ * project back whole whatever its `allow.read` said — an undeclared read
+ * of its own file ran unreported, and an edit to it was a stale hit.
+ *
+ * With `keyed` given (a cached task), a target inside the workspace root
+ * is granted only when it IS a keyed project's directory; every other one
+ * is withheld, since an edit there would not move the key. A target
+ * outside the root lies outside the deny anchor, so granting it is a no-op
+ * either way. Every side of every comparison is canonical: a target always
+ * is, and a directory under a root reached through a link (macOS's `/var`)
+ * is not.
  */
-async function linkedDeps(dirs: readonly string[]): Promise<string[]> {
-  const out = new Set<string>()
-  const scan = async (dir: string, depth: number): Promise<void> => {
+async function linkedDeps(
+  dirs: readonly string[],
+  projectDir: string,
+  workspaceRoot: string,
+  keyed: ReadonlySet<string> | undefined,
+): Promise<{ granted: string[]; withheld: WithheldLink[] }> {
+  const [self, root] = await Promise.all([realpath(projectDir), realpath(workspaceRoot)])
+  const scan = async (dir: string, scope: string): Promise<Array<[string, string, string]>> => {
+    const found: Array<[target: string, link: string, name: string]> = []
     const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
     for (const e of entries) {
       const full = path.join(dir, e.name)
       if (e.isSymbolicLink()) {
         const target = await realpath(full).catch(() => undefined)
-        if (
-          target !== undefined &&
-          !dirs.some((d) => target === d || target.startsWith(d + path.sep))
-        ) {
-          out.add(target)
+        if (target !== undefined && !dirs.some((d) => within(target, d)) && !within(self, target)) {
+          found.push([target, full, scope + e.name])
         }
-      } else if (depth === 0 && e.isDirectory() && e.name.startsWith('@')) {
-        await scan(full, 1)
+      } else if (scope === '' && e.isDirectory() && e.name.startsWith('@')) {
+        found.push(...(await scan(full, `${e.name}/`)))
       }
     }
+    return found
+  }
+  // Merged in `dirs` order, so the link a hint names is the project's own
+  // when both have one.
+  const targets = new Map<string, { link: string; name: string }>()
+  for (const found of await Promise.all(dirs.map((d) => scan(d, '')))) {
+    for (const [target, link, name] of found) {
+      if (!targets.has(target)) targets.set(target, { link, name })
+    }
+  }
+  if (keyed === undefined) return { granted: [...targets.keys()], withheld: [] }
+  const keyedDirs = new Set(await Promise.all([...keyed].map((d) => realpath(d))))
+  const granted: string[] = []
+  const withheld: WithheldLink[] = []
+  for (const [target, { link, name }] of targets) {
+    if (!within(target, root) || keyedDirs.has(target)) granted.push(target)
+    else
+      withheld.push({
+        dir: target,
+        name,
+        target: posixRel(root, target),
+        link: posixRel(workspaceRoot, link),
+      })
   }
-  await Promise.all(dirs.map((d) => scan(d, 0)))
-  return [...out]
+  return { granted, withheld }
 }
 
 /**
- * Ensure each declared output path exists on the host as either an
- * empty file (for literal output specs) or a directory (for globbed
- * specs) so bwrap's --bind can find a real fs entry to mount. Without
- * this, writes inside the sandbox to a non-existent allowWrite path
- * silently disappear (bwrap creates a tmpfs that evaporates on exit).
+ * The line a task denied a withheld dependency gets beside the denial:
+ * what it reached, through which link, and the two ways to make the key
+ * answer for it. Added only when a violation already sits under the
+ * target, so it never reddens a pass.
+ */
+export function withheldLinkLine(taskId: string, w: WithheldLink): string {
+  return (
+    `vx: ${taskId} read \`${w.target}\` through \`${w.link}\`, and its key folds no task of ` +
+    `${w.name}, so an edit there would not re-run it. Add a \`dependsOn\` edge that ` +
+    `reaches one (\`^build\` where ${w.name}#build keys its sources, or a \`source\` task: ` +
+    `\`${w.name}#source\`), or grant and key the files yourself (\`allow.read\` plus ` +
+    `\`cache.inputs.workspaceFiles\`).`
+  )
+}
+
+/** The withheld dependencies a reported denial lies under: each earns its hint. */
+export function reachedWithheld(
+  withheld: readonly WithheldLink[],
+  violations: readonly SandboxViolation[],
+): WithheldLink[] {
+  return withheld.filter((w) =>
+    violations.some((v) => v.path !== undefined && within(v.path, w.dir)),
+  )
+}
+
+/** `p` relative to `from`, with `/` separators. */
+function posixRel(from: string, p: string): string {
+  return path.relative(from, p).split(path.sep).join('/')
+}
+
+/**
+ * `p` is `dir` or below it — by path, so a sibling sharing `dir`'s name
+ * prefix is not. `/` already ends in the separator, and a link to it
+ * holds every project.
+ */
+function within(p: string, dir: string): boolean {
+  return p === dir || p.startsWith(dir.endsWith(path.sep) ? dir : dir + path.sep)
+}
+
+/**
+ * Ensure each declared write path exists on the host as either an empty
+ * file (a literal path) or a directory (a glob's static prefix, or a
+ * literal ending in `/`) so bwrap's --bind can find a real fs entry to
+ * mount. Without this, writes inside the sandbox to a non-existent
+ * allowWrite path silently disappear (bwrap creates a tmpfs that
+ * evaporates on exit).
+ *
+ * A literal that names nothing yet is a FILE — `dist/vx` for `bun build
+ * --outfile dist/vx` — and the task that meant a directory (`write:
+ * ['dist']`, then `mkdir -p dist`) met "File exists" from its own tool,
+ * with the empty file left behind for every later run to meet again
+ * (its `dist/**` clean matches nothing under a file; 2026-09-16). So a
+ * directory is spelled `dist/`, and the files created here are returned
+ * so the caller can take back the ones the task never wrote.
  *
  * `cleanOutputs` ran just before this in the cache-enabled path, so
  * we know any stale content was wiped; what's left is to materialize
@@ -205,9 +379,10 @@ async function linkedDeps(dirs: readonly string[]): Promise<string[]> {
 async function prepareOutputsForBind(
   projectDir: string,
   outputs: readonly string[],
-): Promise<void> {
+): Promise<Placeholder[]> {
+  const placeholders: Placeholder[] = []
   for (const g of outputs) {
-    const hasWildcard = /[*?[\]]/.test(g)
+    const hasWildcard = !isMountableLiteral(g)
     // A grant OUTSIDE the project is the user's own path — never joined
     // onto the project dir, which would create a literal `~` there. Its
     // directory is still created when the grant is a glob, because then
@@ -218,26 +393,177 @@ async function prepareOutputsForBind(
     // reported a network error for an unwritable cache; 2026-09-05).
     if (path.isAbsolute(g) || g.startsWith('~')) {
       if (!hasWildcard) continue
-      const abs = expandHome(staticPrefix(g))
+      const abs = expandHome(grantPrefix(g))
       await mkdir(abs, { recursive: true }).catch(() => undefined)
       continue
     }
-    if (hasWildcard) {
-      const abs = path.join(projectDir, staticPrefix(g))
+    if (hasWildcard || g.endsWith('/')) {
+      const abs = path.join(projectDir, hasWildcard ? grantPrefix(g) : g)
       await mkdir(abs, { recursive: true })
     } else {
       const abs = path.join(projectDir, g)
       // Whatever is already there is what the task meant — a grant on the
       // project dir itself is a directory, and touching it as a file is
-      // an EISDIR, not a missing bind.
-      if (await stat(abs).catch(() => undefined)) continue
+      // an EISDIR, not a missing bind. `lstat`, and an exclusive create: a
+      // dangling link at the grant made vx, unsandboxed, create the empty
+      // file at the link's target in another project (item 1003).
+      if (await lstat(abs).catch(() => undefined)) continue
       await mkdir(path.dirname(abs), { recursive: true })
-      await Bun.write(abs, '')
+      await writeFile(abs, '', { flag: 'wx' })
+      placeholders.push({ path: abs, mtimeMs: (await lstat(abs)).mtimeMs })
     }
   }
+  return placeholders
+}
+
+/**
+ * The walls a project's grants stop at: its nested projects, the
+ * repository and vx's directory (item 1010). A read grant around one is
+ * punched (`punchWalls`); a write grant whose bind would hold one — a file
+ * grant binds its directory on Linux, so `write: ['out.txt']` in a root
+ * project bound the whole workspace writable, `.git` included — is
+ * refused, as there is no writable bind that leaves a wall out.
+ */
+function wallOff(
+  config: ResolvedSandboxConfig,
+  workspaceRoot: string,
+  raw: readonly string[],
+): ResolvedSandboxConfig {
+  const walls = raw.map(toRealPath)
+  const home = toRealPath(workspaceRoot)
+  for (const bind of bindableWrites(config.allowWrite)) {
+    // A bind outside the workspace is the user's own path (`/tmp/x`,
+    // `~/.cache/y`), spelled there on purpose; only one inside is judged.
+    if (bind !== home && !bind.startsWith(home + path.sep)) continue
+    const wall = walls.find((w) => w === bind || w.startsWith(bind + path.sep))
+    if (wall === undefined) continue
+    throw new UserError(
+      `exec.sandbox.allow.write: the grant binding ${bind} would make ${wall} writable — another ` +
+        `project's directory, the repository or vx's own. A file grant binds its directory; ` +
+        `grant a directory of the task's own instead, such as "dist/".`,
+    )
+  }
+  return { ...config, allowRead: config.allowRead.flatMap((r) => punchWalls(r, walls)) }
+}
+
+/**
+ * Remove the placeholder files the task never wrote — still empty, mtime
+ * untouched — and return their paths. What the task wrote is its output
+ * and stays; what it did not is vx's own litter, and litter under a
+ * declared output would be archived as the task's (an empty `dist/vx`
+ * saved as a build) or, as a file where the task wanted a directory,
+ * would fail every later run the same way.
+ */
+export async function sweepPlaceholders(placeholders: readonly Placeholder[]): Promise<string[]> {
+  const untouched: string[] = []
+  for (const p of placeholders) {
+    // `lstat`: a link the task put in the placeholder's place is its
+    // output, never vx's litter to remove (item 1003).
+    const st = await lstat(p.path).catch(() => undefined)
+    if (st === undefined || !st.isFile() || st.size !== 0 || st.mtimeMs !== p.mtimeMs) continue
+    await rm(p.path, { force: true })
+    untouched.push(p.path)
+  }
+  return untouched
+}
+
+/**
+ * One sweep, however many askers, each getting the SAME list.
+ *
+ * A failed persistent task has two askers — the child's exit handler and
+ * the readiness failure that reports the hint — and a second
+ * `sweepPlaceholders` cannot serve the later one: the first one's `rm`
+ * already happened, so it finds nothing and names nothing. Collecting
+ * both lists and unioning them does not close it either, because a sweep
+ * still between its `rm` and its return has published nothing yet, and
+ * the union is then empty on both sides. Sharing the one promise is what
+ * makes the answer independent of who asked first.
+ */
+export function placeholderSweeper(placeholders: readonly Placeholder[]): () => Promise<string[]> {
+  let once: Promise<string[]> | undefined
+  return () => (once ??= sweepPlaceholders(placeholders))
+}
+
+/**
+ * The line a failed task gets for a placeholder it never wrote. Not a
+ * diagnosis — the task may have died before its first write — but the
+ * one clue to the trap: a grant that meant a directory is bound as a
+ * file, and the task's own `mkdir` says only "File exists". Added when
+ * the task already failed and the sandbox reported nothing else, so it
+ * never reddens a pass and never buries a real denial.
+ */
+export function untouchedPlaceholderLine(projectDir: string, placeholder: string): string {
+  const rel = path.relative(projectDir, placeholder).split(path.sep).join('/')
+  return (
+    `vx: the sandbox write grant \`${rel}\` named nothing on disk, so vx bound it as an empty ` +
+    `file, which the task never wrote (removed again). If the task creates a directory there ` +
+    `("File exists" from its own mkdir), spell the grant \`${rel}/\` — a literal without the ` +
+    `slash is a file.`
+  )
 }
 
 /** `~/x` against the user's home; anything else unchanged. */
 function expandHome(p: string): string {
   return p.startsWith('~') ? path.join(homedir(), p.slice(1)) : p
 }
+
+/** Where a command may have written: nothing a key reads, its own project, or any project. */
+export type WriteReach = 'none' | 'project' | 'workspace'
+
+/**
+ * Where a task that ran a command may have written files no declaration
+ * names — the files whose run-start facts (the git snapshot, its index
+ * OIDs, the `package.json` digest) a later key must not reuse (item 743).
+ *
+ * A cached task declares its outputs and is held to them. A task with no
+ * `cache` block can declare none, so it may have written anywhere
+ * `commandWriteReach` says. An unsandboxed write into another project is
+ * out of contract, as it is for a cached task.
+ */
+export function undeclaredWriteReach(node: TaskNode, workspaceRoot: string): WriteReach {
+  if (node.config.cache !== undefined) return 'none'
+  return commandWriteReach(node, workspaceRoot)
+}
+
+/**
+ * Where a task's command may write at all: anywhere in its own project
+ * (`'project'`), unless a sandbox bounds it — no write grant writes nothing
+ * a key reads (`'none'`), and a grant that leaves the project for elsewhere
+ * in the workspace reaches every project (`'workspace'`). A grant outside
+ * the workspace reaches no input. A cached task's reach is where it may
+ * rewrite its own inputs in place (a formatter), which the stability gate
+ * reads (stable-keys.ts).
+ */
+export function commandWriteReach(node: TaskNode, workspaceRoot: string): WriteReach {
+  const exec = node.config.exec
+  if (exec === undefined) return 'none'
+  if (exec.sandbox === undefined) return 'project'
+  let reach: 'none' | 'project' = 'none'
+  for (const grant of exec.sandbox.allow?.write ?? []) {
+    const abs = path.resolve(node.projectDir, expandHome(grantPrefix(grant)))
+    if (within(abs, node.projectDir)) reach = 'project'
+    else if (within(abs, workspaceRoot) || within(workspaceRoot, abs)) return 'workspace'
+  }
+  return reach
+}
+
+/**
+ * May this task's command rewrite a file the workspace fingerprint folds
+ * (a lockfile, `pnpm-workspace.yaml`)? Those sit at the workspace root, so
+ * an unsandboxed task may only when the root is its own project (`pnpm
+ * install` without `--frozen-lockfile` in a root task); a sandboxed one
+ * when a write grant covers one. Anyone else writing there crosses a
+ * project boundary, out of contract.
+ */
+export function mayWriteFingerprint(node: TaskNode, workspaceRoot: string): boolean {
+  const exec = node.config.exec
+  if (exec === undefined) return false
+  if (exec.sandbox === undefined) return node.projectDir === workspaceRoot
+  for (const grant of exec.sandbox.allow?.write ?? []) {
+    const abs = path.resolve(node.projectDir, expandHome(grantPrefix(grant)))
+    for (const f of WORKSPACE_FINGERPRINT_FILES) {
+      if (within(path.join(workspaceRoot, f), abs)) return true
+    }
+  }
+  return false
+}

package/src/orchestrator/save-lane.ts

@@ -4,8 +4,10 @@
 // artifact against ~5 ms of execution on the 1,000-project bench
 // (2026-09-10) — so holding the slot for it serialized I/O behind CPU.
 // A bounded number run at once (memory: each pack holds an artifact's
-// bytes), the run drains them before the upload drain, and a save that
-// fails degrades to a miss next time, said once — the task's work ran.
+// bytes); the scheduler finishes a task only once its save has settled
+// (`settledOf`), so a run ends with every save in the cache; and a save
+// that fails degrades to a miss next time, said once — the task's work
+// ran.
 
 export interface SaveLane {
   /**
@@ -15,8 +17,6 @@ export interface SaveLane {
    * same task in another run (admission's in-flight join).
    */
   defer(save: () => Promise<void>): Promise<void>
-  /** Settle every deferred save, started or queued. */
-  drain(): Promise<void>
 }
 
 export function createSaveLane(cap: number, onError: (err: unknown) => void): SaveLane {
@@ -40,8 +40,5 @@ export function createSaveLane(cap: number, onError: (err: unknown) => void): Sa
         else queue.push({ save, settle })
       })
     },
-    async drain() {
-      while (running.size > 0) await Promise.all([...running])
-    },
   }
 }