@vzn/vx 0.0.595 → 0.0.596

package/src/cli/cache.ts

@@ -85,10 +85,15 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
     if (a === '--older-than' || a?.startsWith('--older-than=')) {
       const v = a === '--older-than' ? args[++i] : a.slice('--older-than='.length)
       if (v === undefined || v === '') {
-        return { error: `--older-than requires a value (e.g. 30d, 24h, 60m)` }
+        return {
+          error: `--older-than requires a value: a duration like 30d, 24h or 60m${seeHelp('cache')}`,
+        }
       }
       const ms = parseDuration(v)
-      if (ms === null) return { error: `invalid duration: ${v} (e.g. 30d, 24h, 60m)` }
+      if (ms === null)
+        return {
+          error: `--older-than must be a duration like 30d, 24h or 60m (got ${v})${seeHelp('cache')}`,
+        }
       // `0d` evicts everything ever cached. That is far more often a
       // computed-to-zero retention than an intent, and no other flag
       // combination expresses "wipe the cache" — so refuse it and name
@@ -102,10 +107,11 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
     } else if (a === '--max-size' || a?.startsWith('--max-size=')) {
       const v = a === '--max-size' ? args[++i] : a.slice('--max-size='.length)
       if (v === undefined || v === '') {
-        return { error: `--max-size requires a value (e.g. 500M, 1G)` }
+        return { error: `--max-size requires a value: a size like 500M or 1G${seeHelp('cache')}` }
       }
       const bytes = parseSize(v)
-      if (bytes === null) return { error: `invalid size: ${v} (e.g. 500M, 1G)` }
+      if (bytes === null)
+        return { error: `--max-size must be a size like 500M or 1G (got ${v})${seeHelp('cache')}` }
       if (bytes === 0) {
         return {
           error: `--max-size 0 would evict every entry — to clear the cache, delete the cache store \`vx info\` names`,

package/src/cli/foreign-flags.ts

@@ -375,7 +375,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     names: ['--preflight'],
     value: false,
     outcome: 'refuse',
-    vx: '`turboCache()` sends no CORS preflight: drop it',
+    vx: 'set `turboCache({ preflight: true })` or `TURBO_PREFLIGHT=1`',
   },
   {
     runner: 'turbo',

package/src/cli/last.ts

@@ -60,7 +60,10 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
       if (spaced) i++
       const n = Number(lv)
       if (!Number.isInteger(n) || n < 1 || n > 500) {
-        return { ...out, error: `invalid --list: ${lv} (expected 1..500)` }
+        return {
+          ...out,
+          error: `--list must be a whole number from 1 to 500 (got ${lv})${seeHelp('last')}`,
+        }
       }
       out.list = n
       continue

package/src/cli/run.ts

@@ -12,7 +12,7 @@ import {
   type RunOptions,
   type RunResult,
 } from '../orchestrator/index.js'
-import type { ContinueMode } from '../graph/index.js'
+import type { ContinueMode, TaskOutcome } from '../graph/index.js'
 import { type CachePolicy, FULL_CACHE_POLICY, parseCachePolicy } from '../cache/index.js'
 import { affectedFilterFor, findCwdSelection, pickTask, resolveFilters } from './select.js'
 import { nxTargetHint, taskNamesHere } from './task-verb.js'
@@ -486,6 +486,7 @@ export async function resolveRunOptions(
   parsed: RunArgs,
   cwd: string,
   tasks: readonly string[],
+  verb: 'run' | 'watch' = 'run',
 ): Promise<RunOptions | { error: string } | { nothingSelected: string }> {
   for (const t of tasks) {
     const idx = t.indexOf('#')
@@ -557,8 +558,7 @@ export async function resolveRunOptions(
       const nx = await nxTargetHint(tasks, cwd)
       if (nx !== null) return { error: nx }
       return {
-        error:
-          'not inside a project. Pass --all for every project, --filter <pattern> to filter, or run from within a project directory.',
+        error: `not inside a project: run from a project directory, or pass --all or --filter <pattern>${seeHelp(verb)}`,
       }
     }
     projects = [cwdProject.name]
@@ -726,6 +726,25 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     return 0
   }
 
+  // The report prints above the footer: nothing prints below it (owner).
+  // Rendered once, however many sinks asked for it; a kept server's crash
+  // after the footer re-renders the file's copy (C-53).
+  const wantsReport = parsed.report === 'markdown' || parsed.reportFile !== undefined
+  let reported: { outcomes: readonly TaskOutcome[]; md: string } | undefined
+  if (wantsReport) {
+    opts.beforeFooter = (outcomes, ok) => {
+      reported = {
+        outcomes,
+        md: formatRunReportMarkdown({ ok, outcomes: outcomes.map(projectOutcome) }),
+      }
+      // `--report` writes stdout. The report ITSELF is machine-clean, but
+      // stdout is not vx's alone — the status logger writes there too, so
+      // `--report=markdown >> "$GITHUB_STEP_SUMMARY"` captures every frame,
+      // meter bar and `::group::` command above the table. `--report-file`
+      // is the redirect-free form.
+      return parsed.report === 'markdown' ? reported.md : ''
+    }
+  }
   // A run executes in THIS process, always. Where an individual task's
   // command runs is the `executor` capability's business (per task, with
   // the scheduler, cache, retries and telemetry unchanged above it); there
@@ -735,17 +754,14 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     process.stderr.write(`vx run: ${summary.refused}\n`)
     return 1
   }
-  const result: RunResult = { ok: summary.ok, outcomes: summary.outcomes.map(projectOutcome) }
-  // Report generation is post-run, gated on the flags — zero cost when
-  // both are absent. Rendered once, however many sinks asked for it.
-  if (parsed.report === 'markdown' || parsed.reportFile !== undefined) {
-    const md = formatRunReportMarkdown(result)
-    // `--report` writes stdout. The report ITSELF is machine-clean, but
-    // stdout is not vx's alone — the status logger writes there too, so
-    // `--report=markdown >> "$GITHUB_STEP_SUMMARY"` captures every frame,
-    // meter bar and `::group::` command above the table. `--report-file`
-    // is the redirect-free form.
-    if (parsed.report === 'markdown') process.stdout.write(md)
+  if (wantsReport) {
+    const md =
+      reported?.outcomes === summary.outcomes
+        ? reported.md
+        : formatRunReportMarkdown({
+            ok: summary.ok,
+            outcomes: summary.outcomes.map(projectOutcome),
+          })
     if (parsed.reportFile !== undefined) {
       const target = path.resolve(cwd, parsed.reportFile)
       try {
@@ -768,5 +784,5 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       }
     }
   }
-  return result.ok ? 0 : 1
+  return summary.ok ? 0 : 1
 }

package/src/cli/watch-filter.ts

@@ -179,9 +179,14 @@ export function gitIgnored(workspaceRoot: string, paths: readonly string[]): Set
   // ignored let a pid file in the same window start cycles again. The
   // refused path is skipped and the rest asked again; a refusal before
   // any record outside a work tree is git refusing them all.
-  let rest = paths
+  // Git refuses a path beyond a symbolic link: its ignored pid file read
+  // as an edit and an uncached task re-ran forever. Asked at its real
+  // place, answered as given.
+  const real = paths.map(gitSpeller(workspaceRoot))
+  let from = 0
   let inWorkTree: boolean | undefined
-  while (rest.length > 0) {
+  while (from < paths.length) {
+    const rest = real.slice(from)
     let proc: ReturnType<typeof Bun.spawnSync>
     try {
       proc = Bun.spawnSync({
@@ -201,8 +206,8 @@ export function gitIgnored(workspaceRoot: string, paths: readonly string[]): Set
     const fields = new TextDecoder('utf-8', { ignoreBOM: true }).decode(proc.stdout).split('\0')
     const records = Math.floor(fields.length / 4)
     for (let i = 0; i < records; i++) {
-      const [source, , pattern, p] = fields.slice(i * 4, i * 4 + 4)
-      if (source !== '' && !pattern!.startsWith('!')) ignored.add(p!)
+      const [source, , pattern] = fields.slice(i * 4, i * 4 + 4)
+      if (source !== '' && !pattern!.startsWith('!')) ignored.add(paths[from + i]!)
     }
     // 0: some ignored; 1: none. Anything else is git refusing.
     if (proc.exitCode === 0 || proc.exitCode === 1) return ignored
@@ -216,7 +221,7 @@ export function gitIgnored(workspaceRoot: string, paths: readonly string[]): Set
         }).exitCode === 0
       if (!inWorkTree) return ignored
     }
-    rest = rest.slice(records + 1)
+    from += records + 1
   }
   return ignored
 }
@@ -351,19 +356,59 @@ export function isWorkspaceConfigFile(name: string): boolean {
  */
 const FINGERPRINT_FILES: ReadonlySet<string> = new Set(WORKSPACE_FINGERPRINT_FILES)
 
+/**
+ * Paths as git spells them under `root`: a project reached through a
+ * symlink below the root (`packages/x -> ../shared/x`) is watched at the
+ * link, and git names and answers for its files only at the real place.
+ * The root keeps its own spelling (macOS's `/var` is `/private/var`), the
+ * name its own (the file may be gone); a directory outside the root is
+ * kept as given. Directories are resolved once per speller.
+ */
+export function gitSpeller(root: string): (p: string) => string {
+  const dirs = new Map<string, string>()
+  let realRoot: string | undefined
+  return (p) => {
+    const dir = path.dirname(p)
+    let at = dirs.get(dir)
+    if (at === undefined) {
+      at = dir
+      try {
+        realRoot ??= realPath(root)
+        const rel = path.relative(realRoot, realPath(dir))
+        if (rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel)) {
+          at = path.join(root, rel)
+        }
+      } catch {}
+      dirs.set(dir, at)
+    }
+    return path.join(at, path.basename(p))
+  }
+}
+
 /**
  * The files under the workspace git lists, tracked and untracked, ignored
  * ones aside, and every directory above one (git lists no directory, and
  * a project moved away whole is one event on its directory): what existed
  * when watch armed, so a path born and gone since is told from a deletion
- * (watch-judge.ts). Undefined when git cannot answer: no inventory, every
- * gone path is a deletion as before.
+ * (watch-judge.ts). `tracked` is the files git tracks: a user edits those,
+ * so a server cannot be blamed for one. Undefined when git cannot answer:
+ * no inventory, every gone path is a deletion as before.
  */
-export function gitFiles(workspaceRoot: string): Set<string> | undefined {
+export function gitFiles(
+  workspaceRoot: string,
+): { listed: Set<string>; tracked: Set<string> } | undefined {
   let proc: ReturnType<typeof Bun.spawnSync>
   try {
     proc = Bun.spawnSync({
-      cmd: [executablePath('git'), 'ls-files', '-z', '--cached', '--others', '--exclude-standard'],
+      cmd: [
+        executablePath('git'),
+        'ls-files',
+        '-z',
+        '-t',
+        '--cached',
+        '--others',
+        '--exclude-standard',
+      ],
       cwd: workspaceRoot,
       stdout: 'pipe',
       stderr: 'ignore',
@@ -373,13 +418,19 @@ export function gitFiles(workspaceRoot: string): Set<string> | undefined {
   }
   if (proc.exitCode !== 0) return undefined
   const files = new Set<string>()
-  for (const p of new TextDecoder('utf-8', { ignoreBOM: true }).decode(proc.stdout).split('\0')) {
-    if (p.length === 0) continue
+  const tracked = new Set<string>()
+  for (const entry of new TextDecoder('utf-8', { ignoreBOM: true })
+    .decode(proc.stdout)
+    .split('\0')) {
+    if (entry.length === 0) continue
+    // `-t` prefixes a tag and a space; `?` is untracked.
+    const p = entry.slice(2)
     // An untracked nested repository is listed as `dir/`.
     let abs = path.join(workspaceRoot, p.endsWith('/') ? p.slice(0, -1) : p)
     files.add(abs)
+    if (entry[0] !== '?') tracked.add(abs)
     for (abs = path.dirname(abs); abs !== workspaceRoot && !files.has(abs); abs = path.dirname(abs))
       files.add(abs)
   }
-  return files
+  return { listed: files, tracked }
 }

package/src/cli/watch-judge.ts

@@ -5,7 +5,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { xxh3 } from '../util/index.js'
-import { gitIgnored } from './watch-filter.js'
+import { gitIgnored, gitSpeller } from './watch-filter.js'
 import { modifiedBefore } from './watch-fs.js'
 
 const ABSENT = -1n
@@ -63,6 +63,8 @@ export interface JudgeContext {
   fenced?(ownDir: string, abs: string): boolean
   /** The files git listed at the arm; absent when git could not answer. */
   existedAtArm?: ReadonlySet<string>
+  /** The files git tracked at the arm; absent when git could not answer. */
+  trackedAtArm?: ReadonlySet<string>
 }
 
 export class ChangeJudge {
@@ -124,14 +126,14 @@ export class ChangeJudge {
   // the moment between a judgement and that cycle's keys, and gone by the
   // next judgement, was read and its deletion re-runs nothing. Git lists
   // no ignored path, so one of those is a deletion as before.
-  private sameState(abs: string, ignored = false): boolean {
+  private sameState(abs: string, ignored: boolean, spell: (p: string) => string): boolean {
     const state = settledState(abs)
     const prev = this.lastState.get(abs)
     this.lastState.set(abs, state)
     if (prev !== undefined) return prev === state
     if (state === ABSENT) {
       const listed = this.ctx.existedAtArm
-      return !ignored && listed !== undefined && !listed.has(abs) && !this.inNestedRepo(abs)
+      return !ignored && listed !== undefined && !listed.has(spell(abs)) && !this.inNestedRepo(abs)
     }
     return modifiedBefore(abs, this.ctx.armedAt)
   }
@@ -146,13 +148,17 @@ export class ChangeJudge {
     return false
   }
 
-  private writtenDuringLastCycle(abs: string, openWhileHeld = false): boolean {
+  /** `spell` (git's spelling, see `gitSpeller`) given: a held server's write counts outside a cycle too. */
+  private writtenDuringLastCycle(abs: string, spell?: (p: string) => string): boolean {
     // A server the last cycle left running is still that cycle's: its
     // writes land after the cycle ended, and with a closed window a dev
     // server that rewrites a log in its project restarted itself forever
     // with no word of it, 12 restarts in 8 s (item 948). The initial run's
-    // server is one too, from the arm on.
-    const open = openWhileHeld && this.ctx.held()
+    // server is one too, from the arm on. Not a tracked file: that is the
+    // user's edit, and three saves of one source file were told to
+    // .gitignore it as a server's write (WD-7).
+    const open =
+      spell !== undefined && this.ctx.held() && this.ctx.trackedAtArm?.has(spell(abs)) !== true
     if (this.lastCycle === undefined && !open) return false
     try {
       const m = fs.statSync(abs).mtimeMs
@@ -165,6 +171,7 @@ export class ChangeJudge {
 
   judge(): string | undefined {
     const ignored = gitIgnored(this.ctx.workspaceRoot, [...this.pending.keys()])
+    const spell = gitSpeller(this.ctx.workspaceRoot)
     let first: string | undefined
     let firstAbs: string | undefined
     // `sameState` before the `first` test, never after it: it is what
@@ -190,7 +197,7 @@ export class ChangeJudge {
     let gone: [label: string, abs: string] | undefined
     for (const [p, l] of this.pending) {
       if (ignored.has(p) && !editForUncached(p)) continue
-      if (this.sameState(p, ignored.has(p)) || first !== undefined) continue
+      if (this.sameState(p, ignored.has(p), spell) || first !== undefined) continue
       if (!fs.existsSync(p)) {
         gone ??= [l, p]
         continue
@@ -201,7 +208,7 @@ export class ChangeJudge {
     if (first === undefined && gone !== undefined) [first, firstAbs] = gone
     this.pending.clear()
     const byServer = firstAbs !== undefined && this.ctx.held()
-    if (firstAbs === undefined || !this.writtenDuringLastCycle(firstAbs, true)) {
+    if (firstAbs === undefined || !this.writtenDuringLastCycle(firstAbs, spell)) {
       this.streak.n = 0
       return first
     }

package/src/cli/watch.ts

@@ -103,7 +103,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   }
 
   const cwd = process.cwd()
-  const resolved = await resolveRunOptions(parsed, cwd, parsed.tasks)
+  const resolved = await resolveRunOptions(parsed, cwd, parsed.tasks, 'watch')
   if ('error' in resolved) {
     process.stderr.write(`vx watch: ${resolved.error}\n`)
     return 1
@@ -471,8 +471,8 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
 
   /** The instant the watchers go live, on the mtime clock (see `fsClockNow`): a path last modified before it is the initial run's, not an edit. */
   const armedAt = fsClockNow(cacheDir)
-  /** What existed at the arm, so a file born and gone since is no deletion (watch-judge.ts). */
-  const existedAtArm = gitFiles(workspaceRoot)
+  /** What existed and was tracked at the arm, so a file born and gone since is no deletion and a tracked one is the user's edit (watch-judge.ts). */
+  const atArm = gitFiles(workspaceRoot)
   /** Which settled paths are changes (watch-judge.ts); `pending` holds what fired since. */
   const changes = new ChangeJudge({
     workspaceRoot,
@@ -480,7 +480,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     held: () => held !== undefined,
     uncached: () => uncached,
     fenced: (ownDir, abs) => fenced(ownDir, abs),
-    ...(existedAtArm !== undefined ? { existedAtArm } : {}),
+    ...(atArm !== undefined ? { existedAtArm: atArm.listed, trackedAtArm: atArm.tracked } : {}),
   })
   /** Per-project arms by directory, so `rearm` can add and drop them. */
   const perProject = new Map<string, WatchHandle>()

package/src/config.ts

@@ -292,10 +292,10 @@ export interface SandboxConfig {
 
 /** The denials `sandbox.ignore` can leave out of the report: patterns per class. */
 export interface SandboxIgnore {
-  read?: string[]
-  write?: string[]
-  systemInfo?: string[]
-  network?: string[]
+  read?: readonly string[]
+  write?: readonly string[]
+  systemInfo?: readonly string[]
+  network?: readonly string[]
 }
 
 export interface SandboxGrants {
@@ -304,29 +304,29 @@ export interface SandboxGrants {
    * `node_modules`, NOT `cache.inputs.files`. A task that reads its own
    * source in the sandbox says so here.
    */
-  read?: string[]
+  read?: readonly string[]
   /**
    * Writable paths or globs. The task can write NOTHING without these:
    * declaring `cache.outputs.files` grants no write, and a task whose
    * only declaration is its outputs writes into a tmpfs that evaporates
    * (vx then warns that `cache.outputs` matched no files).
    */
-  write?: string[]
+  write?: readonly string[]
   /**
    * Reachable domains, `['*.example.com']` a pattern. The proxy is the
    * run's: it filters every sandboxed task against the union of the lists
    * the run's tasks declare, so `true` adds no domain and reaches only
    * those (none in a run with no list). Omitted adds none either.
    */
-  network?: true | string[]
+  network?: true | readonly string[]
   /**
    * Kernel information the task may query, by info type — the name that
    * appears in a denial, e.g. `vfs.disk-space` (every Bun and git process
    * probes free space at startup).
    */
-  systemInfo?: string[]
+  systemInfo?: readonly string[]
   /** Unix socket paths the task may connect to. `true` allows any. */
-  unixSockets?: true | string[]
+  unixSockets?: true | readonly string[]
   /**
    * Bind and reach localhost ports — a test that boots a server for
    * itself. A port LIST additionally makes those ports reachable from
@@ -335,9 +335,9 @@ export interface SandboxGrants {
    * namespace, each listed port is bridged out to the host's loopback;
    * on macOS the host already sees them and the list means `true`.
    */
-  localBinding?: boolean | number[]
+  localBinding?: boolean | readonly number[]
   /** macOS: Mach service names the task may look up. */
-  machLookup?: string[]
+  machLookup?: readonly string[]
   /** Acquire a TTY. Rare outside interactive tools. */
   pty?: boolean
   /** Write to `.git/config`. Most build tools should not. */
@@ -346,7 +346,7 @@ export interface SandboxGrants {
 
 export interface SandboxDenials {
   /** Domains blocked even if `allow.network` would admit them. */
-  network?: string[]
+  network?: readonly string[]
 }
 
 export interface ExecConfig {
@@ -458,7 +458,7 @@ export interface ExecEnv {
    * folded into the cache key — for things like CI flags, regional
    * vars, secrets that change between machines without affecting output.
    */
-  passThrough?: string[]
+  passThrough?: readonly string[]
   /**
    * Explicit `name: value` pairs. The values are set on the child AND
    * folded into the cache key (they are literal in your config, captured
@@ -471,7 +471,7 @@ export interface ExecEnv {
    * hold `TOKEN`, `SECRET`, `KEY`, `PASSWORD`, `PASSWD` or `CREDENTIAL`
    * are masked without it; this reaches `GH_PAT`, `NPM_AUTH`.
    */
-  secret?: string[]
+  secret?: readonly string[]
 }
 
 export interface CacheConfig {
@@ -488,7 +488,7 @@ export interface CacheOutputs {
    * Outputs are not filtered through gitignore — typical artifact dirs
    * like `dist/` and `coverage/` are captured normally even when ignored.
    */
-  files: string[]
+  files: readonly string[]
   /**
    * Files produced OUTSIDE the project dir, as workspace-root-relative
    * globs (the Turbo `$TURBO_ROOT$` / Nx `{workspaceRoot}` escape
@@ -500,7 +500,7 @@ export interface CacheOutputs {
    * like overlapping `files` (vx cleans declared outputs before a run
    * and before a restore, so the second would delete the first's).
    */
-  workspaceFiles?: string[]
+  workspaceFiles?: readonly string[]
 }
 
 export interface CacheInputs {
@@ -514,7 +514,7 @@ export interface CacheInputs {
    * files are excluded automatically — a task cannot invalidate itself,
    * and cannot read across project boundaries.
    */
-  files: string[]
+  files: readonly string[]
   /**
    * Workspace-root-relative globs (the Turbo `$TURBO_ROOT$` / Nx
    * `{workspaceRoot}` equivalent), for inputs that live outside the
@@ -528,7 +528,7 @@ export interface CacheInputs {
    * Declared outputs (both `outputs` fields) are excluded
    * automatically (a task cannot invalidate itself).
    */
-  workspaceFiles?: string[]
+  workspaceFiles?: readonly string[]
   /**
    * Env var names whose runtime values from parent `process.env` are
    * folded into the cache key. **Independent of `exec.env`** — declaring
@@ -536,7 +536,7 @@ export interface CacheInputs {
    * invalidation. To both forward AND track, list the name in both
    * `exec.env.passThrough` and here.
    */
-  env?: string[]
+  env?: readonly string[]
   /**
    * Which upstream tasks' cache keys participate in this task's key.
    * Uses the same Turbo/Nx micro-syntax as `dependsOn`, plus
@@ -565,7 +565,7 @@ export interface CacheInputs {
    * lock, the OUTPUT is resolved live every run — correct under
    * `--frozen`. Use for project-specific runtime probes.
    */
-  runtime?: string[]
+  runtime?: readonly string[]
   /**
    * Like `runtime`, but commands run at the WORKSPACE ROOT and are
    * deduped GLOBALLY per command across the whole run — a `node -v`
@@ -573,7 +573,7 @@ export interface CacheInputs {
    * analog of `workspaceFiles`: per-task, root-anchored. Use for global
    * tool versions, OS info, etc.
    */
-  workspaceRuntime?: string[]
+  workspaceRuntime?: readonly string[]
 }
 
 /**

package/src/exec/proc-sample.ts

@@ -26,7 +26,7 @@ interface Proc {
 
 /**
  * Linux's `/proc/<pid>/stat` counts CPU in USER_HZ ticks, fixed at 100 by
- * the ABI on every architecture; `tests/proc-sample.test.ts` pins it by
+ * the ABI on every architecture; `tests/proc-sample.unsafe.test.ts` pins it by
  * burning a known span and reading it back.
  */
 const TICK_MS = 10

package/src/exec/sandbox-paths.ts

@@ -82,7 +82,7 @@ export function localBindingOn(c: { localBinding?: boolean | readonly number[] }
  * rest of the host is mounted read-only), or under a read grant, a write
  * grant or a baseline read, by its canonical path. A path no grant holds
  * under a denial is not there inside the sandbox, which the shell reports
- * as "not found" with no denial a trace can see (an `execve`).
+ * as "not found": a PATH search is a stat, which the trace does not stop on.
  */
 export function sandboxReads(
   sandbox: {