@vzn/vx 0.0.652 → 0.0.653

package/src/exec/sandbox-binds.ts

@@ -13,7 +13,8 @@ import {
   toRealPath,
   unique,
 } from './sandbox-paths.js'
-import type { SandboxedRunArgs } from './sandbox-runtime.js'
+import { shellQuote } from './runner.js'
+import type { ResolvedSandboxConfig, SandboxedRunArgs } from './sandbox-runtime.js'
 import * as ui from '../ui/index.js'
 
 type SrtModule = typeof import('@anthropic-ai/sandbox-runtime')
@@ -40,6 +41,48 @@ export function bindableWrites(paths: readonly string[]): string[] {
   return unique(paths.filter((p) => !holdsGlobChar(p)).map(bindOf))
 }
 
+/**
+ * Linux: each write grant spelled through a link in the project, as the
+ * bind that puts it where the task names it: `[source, at]`, the grant's
+ * own bind and its twin under the link. A file grant binds its directory,
+ * so its twin is the link's; a link that is the file itself sits in the
+ * bound directory already and needs none. SRT skips a write path that is
+ * a sibling link (it reads one as leaving its tree), so vx lays these
+ * itself (`withLinkedWrites`).
+ */
+export function linkedWriteBinds(
+  linked: ResolvedSandboxConfig['linkedWrites'],
+): Array<readonly [string, string]> {
+  if (process.platform !== 'linux' || linked === undefined) return []
+  const out: Array<readonly [string, string]> = []
+  for (const { link, target } of linked) {
+    if (holdsGlobChar(target) || holdsGlobChar(link)) continue
+    const source = bindOf(target)
+    const at = source === target ? link : path.dirname(link)
+    if (at !== source && !out.some(([, a]) => a === at)) out.push([source, at])
+  }
+  return out
+}
+
+/**
+ * Linux: SRT's bwrap line with each `linkedWriteBinds` pair bound last,
+ * before the `--` that ends bwrap's options: after the masks and the read
+ * grants, so none lands over it. The link's directory is then a mount of
+ * its target, writable as the grant is.
+ */
+export function withLinkedWrites(
+  wrapped: string,
+  binds: ReadonlyArray<readonly [string, string]>,
+): string {
+  if (binds.length === 0) return wrapped
+  for (const m of wrapped.matchAll(/(?:'[^']*'|"[^"]*"|[^\s'"])+/g)) {
+    if (m[0] !== '--') continue
+    const words = binds.map(([s, a]) => `--bind ${shellQuote(s)} ${shellQuote(a)} `).join('')
+    return `${wrapped.slice(0, m.index)}${words}${wrapped.slice(m.index)}`
+  }
+  return wrapped
+}
+
 function bindOf(p: string): string {
   if (!isMountableLiteral(p)) return p
   try {
@@ -162,7 +205,12 @@ const warnedSymlinkPunch = new Set<string>()
  * A grant with no write path under it is returned untouched — the common
  * case costs nothing, not even a readdir.
  */
-export function punchWritePaths(readPath: string, writePaths: readonly string[]): string[] {
+export function punchWritePaths(
+  readPath: string,
+  writePaths: readonly string[],
+  /** Whether a link child's real path may be bound; one it may not is dropped. */
+  reachable: (real: string) => boolean = () => true,
+): string[] {
   // Linux only. The shadowing is a property of bwrap MOUNTS; macOS seatbelt
   // evaluates rules by precedence, so a read grant on a directory and a
   // write grant inside it coexist. Punching there costs the directory
@@ -193,25 +241,57 @@ export function punchWritePaths(readPath: string, writePaths: readonly string[])
     // SRT's config carries no `--symlink`, so the only fix is the grant:
     // say which one, loudly.
     try {
-      if (lstatSync(child).isSymbolicLink()) linked.push(child)
+      if (lstatSync(child).isSymbolicLink()) {
+        // Bound by its target, a link out to a denied place (`node_modules
+        // -> ..`, `shared -> ../b`) granted what the whole grant never did:
+        // bound unpunched, the link stays a link into the deny (item 1006's
+        // glob hit, through the punch).
+        if (!reachable(toRealPath(child))) continue
+        linked.push(child)
+      }
     } catch {
       // vanished between readdir and lstat: nothing to bind either way
     }
-    out.push(...punchWritePaths(child, under))
+    out.push(...punchWritePaths(child, under, reachable))
   }
   if (linked.length > 0 && !warnedSymlinkPunch.has(readPath)) {
     warnedSymlinkPunch.add(readPath)
-    ui.say(
-      'warn',
-      `[vx] sandbox: a write grant under ${readPath} makes its ${linked.length} symlinked ` +
-        `entr${linked.length === 1 ? 'y' : 'ies'} (${linked
-          .slice(0, 3)
-          .map((l) => path.basename(l))
-          .join(', ')}${linked.length > 3 ? ', …' : ''}) plain directories inside the sandbox — ` +
-        `a package resolved through one loses its siblings. Move the write grant (${under
-          .map((w) => path.relative(readPath, w))
-          .join(', ')}) out of it.\n`,
-    )
+    // A link INTO a write grant is that grant under a second name, mounted
+    // read-only: the remedy is to grant the name (`linkedWriteBinds` binds
+    // it writable), not to move the grant.
+    const plain: string[] = []
+    for (const l of linked) {
+      const w = writePaths.find((w) => atOrUnder(toRealPath(l), w))
+      if (w === undefined) {
+        plain.push(l)
+        continue
+      }
+      let dir = false
+      try {
+        dir = statSync(l).isDirectory()
+      } catch {
+        // dangling: granted as a file
+      }
+      ui.say(
+        'warn',
+        `[vx] sandbox: ${l} is a symlink into the write grant ${w}, and the Linux sandbox ` +
+          `mounts it read-only, so a write through it is refused. Grant the link itself to ` +
+          `write through it: ${l}${dir ? '/' : ''}\n`,
+      )
+    }
+    if (plain.length > 0) {
+      ui.say(
+        'warn',
+        `[vx] sandbox: a write grant under ${readPath} makes its ${plain.length} symlinked ` +
+          `entr${plain.length === 1 ? 'y' : 'ies'} (${plain
+            .slice(0, 3)
+            .map((l) => path.basename(l))
+            .join(', ')}${plain.length > 3 ? ', …' : ''}) plain directories inside the sandbox — ` +
+          `a package resolved through one loses its siblings. Move the write grant (${under
+            .map((w) => path.relative(readPath, w))
+            .join(', ')}) out of it.\n`,
+      )
+    }
   }
   return out
 }
@@ -300,9 +380,20 @@ export function buildCustomConfig(
   const c = args.config
   const denyRead = unique([...baselines.denyRead])
   const allowWrite = bindableWrites(unique([...c.allowWrite]))
-  const allowRead = unique(
-    [...baselines.allowRead, ...c.allowRead].flatMap((r) => punchWritePaths(r, allowWrite)),
-  )
+  // A link a write grant is spelled through is bound by vx, not SRT: a
+  // read grant above it is punched around it all the same.
+  const punched = [...allowWrite, ...linkedWriteBinds(c.linkedWrites).map(([, at]) => at)]
+  const reads = [...baselines.allowRead, ...c.allowRead]
+  // Asked only of a link a punch meets: a target under the deny anchor is
+  // bound only where some read grant already reaches it.
+  let fence: { denied: string[]; granted: string[] } | undefined
+  const reachable = (real: string): boolean => {
+    fence ??= { denied: denyRead.map(toRealPath), granted: reads.map(toRealPath) }
+    return (
+      !fence.denied.some((d) => atOrUnder(real, d)) || fence.granted.some((g) => atOrUnder(real, g))
+    )
+  }
+  const allowRead = unique(reads.flatMap((r) => punchWritePaths(r, punched, reachable)))
 
   const custom: Parameters<SrtModule['SandboxManager']['wrapWithSandbox']>[2] = {
     filesystem: {

package/src/exec/sandbox-runtime.ts

@@ -70,6 +70,7 @@ import {
   ESSENTIAL_ENV,
   executablePath,
   helperEnv,
+  holdSecret,
   taskShell,
   grantPrefix,
   isTmpdirRefusal,
@@ -83,9 +84,11 @@ import {
   bindableReads,
   bindableWrites,
   buildCustomConfig,
+  linkedWriteBinds,
   readOnlyMasks,
   scratchWrites,
   widenedEntries,
+  withLinkedWrites,
 } from './sandbox-binds.js'
 import {
   atOrUnder,
@@ -111,6 +114,7 @@ import {
 } from './sandbox-violations.js'
 import {
   closeSignalChannel,
+  groupAlive,
   killTree,
   releaseGroup,
   signalThrough,
@@ -1008,6 +1012,11 @@ export async function initSandbox(opts?: {
   // reload of exactly these fields; the proxy and the wrapper read them
   // through getters, so the run's config is what every task sees.
   SandboxManager.updateConfig(config)
+  // The proxy's session token rides into a networked task's env
+  // (CLOUDSDK_PROXY_PASSWORD, the proxy URLs' password): a task printing
+  // its env put it in the terminal, the cached log and `vx last --log`.
+  const token = SandboxManager.getProxyAuthToken()
+  if (token !== undefined) holdSecret(token)
 }
 
 /**
@@ -1221,6 +1230,8 @@ export interface ResolvedSandboxConfig {
    * no mount holds them. `scratchWrites` decides which still cover a write.
    */
   pendingWrites?: readonly string[]
+  /** Linux: write grants spelled through a link in the project, bound there too (`linkedWriteBinds`). */
+  linkedWrites?: readonly { readonly link: string; readonly target: string }[]
   network?: true | readonly string[]
   denyNetwork?: readonly string[]
   systemInfo?: readonly string[]
@@ -1318,6 +1329,31 @@ function assertWriteStaysHome(grant: string, real: string, projectDir: string):
   )
 }
 
+/**
+ * Linux: a literal write grant spelled through a link in the project
+ * (`gen/` over `gen -> real`), as the task names it: the project's real
+ * directory with the grant's own components, links unresolved. The grant
+ * binds at its real path and bwrap mounts no link, so without a second
+ * bind there the task met "Directory nonexistent", or, under a read
+ * grant of the project, the link bound read-only over the same directory
+ * ("Read-only file system"). Seatbelt judges the resolved path, so macOS
+ * needs none.
+ */
+function linkSpelling(
+  grant: string,
+  real: string,
+  projectDir: string,
+): { link: string; target: string } | undefined {
+  if (process.platform !== 'linux' || grant.startsWith('~') || path.isAbsolute(grant)) return
+  // `gen/**` is the directory whole (`expandGrants`).
+  const whole = /\/\*\*(?:\/\*)?$/
+  const lexical = path.resolve(projectDir, grant.replace(whole, ''))
+  const target = real.replace(whole, '')
+  if (!atOrUnder(lexical, projectDir) || !isMountableLiteral(target)) return
+  const link = path.join(toRealPath(projectDir), path.relative(projectDir, lexical))
+  return link === target ? undefined : { link, target }
+}
+
 /** Where `p` lands through every link on it, a dangling last one included. */
 function throughLinks(p: string, hops = 0): string {
   if (hops > 40) return p
@@ -1352,12 +1388,15 @@ export function resolveSandboxConfig(
   }
   const a = cfg.allow ?? {}
   const pending: string[] = []
+  const linked: Array<{ link: string; target: string }> = []
   const r: ResolvedSandboxConfig = {
     allowRead: expandGrants((a.read ?? []).map(resolve), walls),
     allowWrite: expandGrants(
       (a.write ?? []).map((p) => {
         const real = resolve(p)
         assertWriteStaysHome(p, real, projectDir)
+        const link = linkSpelling(p, real, projectDir)
+        if (link !== undefined) linked.push(link)
         // A directory a write glob matches is writable whole, as Linux's
         // bind of the hit makes it: `<glob>/**` collapses below into the
         // glob and its subtree. SRT compiles a glob as an exact regex, so
@@ -1374,6 +1413,7 @@ export function resolveSandboxConfig(
     ),
   }
   if (pending.length > 0) r.pendingWrites = pending
+  if (linked.length > 0) r.linkedWrites = linked
   if (process.platform === 'darwin') {
     const read = wallsGlobsReach(r.allowRead, walls)
     const write = wallsGlobsReach(r.allowWrite, walls)
@@ -1446,6 +1486,11 @@ export interface SandboxViolation {
    * leaves it hidden.
    */
   via?: string
+  /**
+   * Linux: what a refused `openat`'s flags asked for; for an `openat2`,
+   * whose flags no record names, a read.
+   */
+  opened?: 'read' | 'write'
   ignorable?: readonly ('read' | 'write' | 'network' | 'systemInfo')[]
 }
 
@@ -1613,11 +1658,13 @@ async function wrapIn(
       ? ownGroupCommand(tag, inTmp, args.trace, args.tracePaths === true)
       : { command: taggedCommand, forwards: false, traced: false }
   // The tag leads: SRT keys a record by the wrap's first 100 characters,
-  // and the proxy wait below is the same 190 for every networked task.
+  // and the proxy wait below is the same 190 for every task.
   const inner = [
     process.platform === 'linux' ? `: 'vx-${tag}';` : '',
     ports.length > 0 ? portBridgeInner(ports, tag) : '',
-    process.platform === 'linux' && args.config.network !== undefined ? PROXY_BRIDGE_WAIT : '',
+    process.platform === 'linux' && SandboxManager.getLinuxHttpSocketPath() !== undefined
+      ? PROXY_BRIDGE_WAIT
+      : '',
     grouped.command,
   ]
     .filter((part) => part !== '')
@@ -1688,7 +1735,7 @@ async function wrapIn(
     )
     wrapped =
       (gitGranted ? 'GIT_DISCOVERY_ACROSS_FILESYSTEM=${GIT_DISCOVERY_ACROSS_FILESYSTEM-1} ' : '') +
-      `exec ${readOnlyMasks(wrapped, scratch)}`
+      `exec ${readOnlyMasks(withLinkedWrites(wrapped, linkedWriteBinds(args.config.linkedWrites)), scratch)}`
   }
   if (process.platform === 'linux' && !hostHasIpv6())
     wrapped = `SOCAT_DEFAULT_LISTEN_IP=4 ${wrapped}`
@@ -1815,16 +1862,23 @@ function ownGroupCommand(
 }
 
 /**
- * What strace stops on: the reads, the execs and access probes (a refused
- * `./gen.sh || fallback` passed unreported), and what moves or makes a
- * process's cwd. Not the stat family: a stop per stat cost oxlint 19% and
- * `git status` 30%, where the execs and probes cost nothing measurable, and
+ * What strace stops on: the reads (`openat`, and `open`, musl's open():
+ * traced as openat alone, a sibling under a widened write grant was read
+ * unreported and cached; arm64 has no `open`; an `openat2` never reaches
+ * strace, SRT's write observer takes each one first: `refusedWrites`),
+ * the execs and access probes (a refused
+ * `./gen.sh || fallback` passed unreported), `readlink` (git hashes a link
+ * by its target string: `readlink cfg > out.txt` under a widened grant
+ * cached `v1` and replayed it after `cfg` pointed at `v2`; a stop costs
+ * ~9 µs, 37 ms on 2,000 links, below the A/A noise on oxlint and vx), and
+ * what moves or makes a process's cwd. Not the stat family: a stop per
+ * stat cost oxlint 19% and `git status` 30%, where the execs and probes cost nothing measurable, and
  * vx's own no-op run 69% (pr-bench, 495 → 835 ms, 2026-10-23). So a tool
  * that stats before it opens, as Ubuntu 26's cat (uutils) does, refused
  * nothing the trace sees.
  */
 const TRACED_CALLS =
-  'trace=openat,execve,?access,faccessat,?faccessat2,chdir,fchdir,clone,?clone3,?fork,?vfork'
+  'trace=openat,?open,execve,?access,faccessat,?faccessat2,?readlink,?readlinkat,chdir,fchdir,clone,?clone3,?fork,?vfork'
 
 /** The descriptor an in-sandbox strace writes its trace to (`ownGroupCommand`). */
 const TRACE_FD = 5
@@ -1971,6 +2025,13 @@ export function bridgedPorts(c: Pick<ResolvedSandboxConfig, 'localBinding'>): nu
  * command, until both listen in the task's network namespace, read off
  * /proc/net (IPv4 or IPv6, state 0A). Bounded at ~5 s: a bridge that never
  * listens leaves the command to meet the refusal it met before.
+ *
+ * Every task the run's bridge reaches waits, not only one that lists a
+ * network: one that lists none dials the same proxy, which refuses and
+ * names the host, and that refusal fails it. Waited for only by networked
+ * tasks, it met the closed port instead under load, swallowed the error
+ * and passed with nothing reported (2026-11-06). The wait costs ~4 ms, the
+ * socat's own start.
  */
 const PROXY_BRIDGE_WAIT =
   "( i=0; until grep -qsE ':0C38 [0-9A-F]+:0000 0A' /proc/net/tcp /proc/net/tcp6 && grep -qsE ':0438 [0-9A-F]+:0000 0A' /proc/net/tcp /proc/net/tcp6; do [ $i -ge 500 ] && break; i=$((i+1)); sleep 0.01; done );"
@@ -2159,8 +2220,8 @@ async function hostBridgesListen(ports: readonly number[], tag: string): Promise
   if (!procfsIsOwn()) return
   const want = ports.map((p) => `0100007F:${p.toString(16).toUpperCase().padStart(4, '0')}`)
   const procs = hostBridges.get(tag)?.procs ?? []
-  const until = Date.now() + 5_000
-  while (Date.now() < until && procs.every((p) => p.exitCode === null)) {
+  const until = performance.now() + 5_000
+  while (performance.now() < until && procs.every((p) => p.exitCode === null)) {
     let table: string
     try {
       table = readFileSync('/proc/net/tcp', 'utf8')
@@ -2267,9 +2328,13 @@ const MOUNT_RACE_RETRY_LINE =
  * bwrap's own refusal of a mount gone between its read of the mount table
  * and its remount: a container runtime's transient mount under /tmp
  * (`/newroot/tmp/containerd-mount…`, a `docker build` beside the task on
- * CI). The command never started.
+ * CI). The command never started. Or a path the wrap walls, gone before
+ * bwrap mounts on it: bwrap makes the mount point anew under a read-only
+ * parent (`Can't mkdir /tmp/vx-noscan-0: Read-only file system`, the no-scan
+ * directory removed by another process).
  */
-const BWRAP_MOUNT_GONE = /^bwrap: Can't .*: No such file or directory$/
+const BWRAP_MOUNT_GONE =
+  /^bwrap: Can't (?:.*: No such file or directory|mkdir .*: Read-only file system)$/
 
 /**
  * Run a single task wrapped in the sandbox. Caller must have called
@@ -2420,7 +2485,8 @@ const STRACE_OWN_ERROR = /^(?:[^\s:]*\/)?strace: /
 async function runSandboxedOnce(
   args: SandboxedRunArgs,
 ): Promise<SandboxedRunResult & { tracerFailed: boolean; mountGone: boolean; ranMs: number }> {
-  const start = Date.now()
+  // Elapsed time, not wall time: see runCommand.
+  const start = performance.now()
   const { SandboxManager } = await loadSrt()
   // Linux: SRT's store sees only writes (below), so read denials need
   // the command traced and the trace parsed for denied syscalls. The trace
@@ -2428,7 +2494,7 @@ async function runSandboxedOnce(
   // share a stream. Skipped when strace isn't on PATH — bwrap still
   // enforces structurally; we just lose the structured violation list.
   //
-  // We trace `openat`, the read itself, plus `execve` and the access
+  // We trace the opens, the read itself, plus `execve` and the access
   // probes (`TRACED_CALLS`). Not `statx` / `newfstatat`: a stop per stat
   // is a tax on every stat-heavy task. A probe's ENOENT counts only where
   // the host has the path (`parseStraceViolations`), so a PATH walk past
@@ -2446,12 +2512,12 @@ async function runSandboxedOnce(
   // one gets the slow form rather than no detection.
   const useStrace = await wantsStraceDetection()
   // Before the spawn: what the task creates under a widened grant is its own.
-  const widened = useStrace ? widenedEntries(args.config.allowWrite) : undefined
+  const widened = widenedEntries(args.config.allowWrite)
   const { wrapped, tag, srtCommand, baselines, scratch, forwardsSignals, traced } =
     await wrapSandboxedCommand({
       ...args,
       ...(useStrace ? { trace: useStrace } : {}),
-      ...(widened !== undefined && widened.size > 0 ? { tracePaths: true } : {}),
+      ...(useStrace && widened.size > 0 ? { tracePaths: true } : {}),
     })
   const takeRecords = collectRecords(
     SandboxManager.getSandboxViolationStore(),
@@ -2467,7 +2533,7 @@ async function runSandboxedOnce(
     const signal = stopSignal(args.signal.reason)
     return {
       exitCode: signalExitCode(signal),
-      durationMs: Date.now() - start,
+      durationMs: Math.round(performance.now() - start),
       stdout: '',
       stderr: '',
       signal,
@@ -2515,14 +2581,14 @@ async function runSandboxedOnce(
       rmSync(straceLog, { force: true })
       liveTempFiles.delete(straceLog)
     }
-    const stderr = spawnFailureText(err, args.cwd, SANDBOXED_TASK, wrapped)
+    const stderr = spawnFailureText(err, args.cwd, SANDBOXED_TASK, wrapped, args.env)
     args.onStderr?.(stderr)
     releaseBridges(tag)
     void takeRecords(false)
     afterCommand(SandboxManager)
     return {
       exitCode: 127,
-      durationMs: Date.now() - start,
+      durationMs: Math.round(performance.now() - start),
       stdout: '',
       stderr,
       spawnFailed: true,
@@ -2541,7 +2607,7 @@ async function runSandboxedOnce(
   args.onSpawn?.(proc.pid)
   const watch = process.platform === 'linux' ? watchTree(proc.pid) : undefined
   const timeout = armTimeout(proc, args.timeoutMs)
-  const armedAt = Date.now()
+  const armedAt = performance.now()
   const ac = new AbortController()
   // The unfinished last line of stderr, and whether a line was strace's.
   let partial = ''
@@ -2570,7 +2636,7 @@ async function runSandboxedOnce(
   // OR a clean exit that backgrounds a process) can't hang the run — timeout
   // aborts at once, otherwise drainOrAbort bounds the post-exit drain.
   await proc.exited
-  const ranMs = Date.now() - armedAt
+  const ranMs = Math.round(performance.now() - armedAt)
   const looked = watch?.stop()
   await timeout.settle()
   let cut = false
@@ -2581,6 +2647,9 @@ async function runSandboxedOnce(
   const cutLine = ends.own(POST_EXIT_CUT_LINE)
   if (cut) args.onStderr?.(cutLine)
   const stderr = cut ? streamed + cutLine : streamed
+  // As runCommand: a leftover holding no pipe is still in the group. Under
+  // Linux's pid namespace it died with the command; macOS keeps it.
+  const left = cut || groupAlive(proc)
   args.liveChildren?.delete(proc)
   releaseGroup(proc)
   closeSignalChannel(proc)
@@ -2659,6 +2728,7 @@ async function runSandboxedOnce(
             bindableWrites(args.config.allowWrite),
             scratch,
             [...baselines.allowRead, ...bindableReads(args.config.allowRead)],
+            { entries: widened, granted: args.config.allowWrite },
           ),
           ...refusedConnections(records.map((v) => v.line)),
         ]
@@ -2734,20 +2804,22 @@ async function runSandboxedOnce(
       config: args.config,
       skip: [taskTmpRoot()],
     })
-    if (hidden.length > 0) violations.push(hiddenReadsHint(hidden, args.reportWithin))
+    if (hidden.length > 0)
+      violations.push(hiddenReadsHint(hidden, baselines.denyRead, args.reportWithin))
   }
 
   afterCommand(SandboxManager)
 
   return {
     exitCode,
-    durationMs: Date.now() - start,
+    durationMs: Math.round(performance.now() - start),
     stdout,
     stderr,
     violations,
     ...(typeof proc.signalCode === 'string' ? { signal: proc.signalCode } : {}),
     ...(timeout.timedOut() ? { timedOut: true } : {}),
-    ...(cut ? { leftRunning: true } : {}),
+    ...(timeout.sigkilled() ? { killedAfterGrace: true } : {}),
+    ...(left ? { 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
@@ -2792,15 +2864,7 @@ function outsideWritesHint(
 ): SandboxViolation {
   const shown = paths.slice(0, 5).join(', ')
   const more = paths.length > 5 ? ` and ${paths.length - 5} more` : ''
-  const home = toRealPath(os.homedir())
-  const dir = path.dirname(paths[0]!)
-  // In the workspace, from the project, as a committed config spells it:
-  // the absolute path held only on the machine that printed it.
-  const spelled = walled.some((w) => atOrUnder(dir, toRealPath(w)))
-    ? path.relative(toRealPath(within), dir) || '.'
-    : atOrUnder(dir, home)
-      ? `~${dir.slice(home.length)}`
-      : dir
+  const spelled = grantSpelling(path.dirname(paths[0]!), walled, within)
   const refused =
     `vx: the sandbox refused writes outside the project, which are not reported as ` +
     `violations: ${shown}${more}.`
@@ -2866,19 +2930,52 @@ function hostTempRoots(): string[] {
   return [...new Set(['/tmp', '/var/tmp', os.tmpdir()].map(toRealPath))]
 }
 
-function hiddenReadsHint(paths: readonly string[], within: string): SandboxViolation {
+/**
+ * The hint for reads the wall hid outside the project. A path under a
+ * deny entry other than the ones holding the project (a credential store
+ * or its link's target, vx's own store, the repository's git data outside
+ * the workspace) is walled on purpose and never the suggested grant: an
+ * agent applies a suggestion as given, and `cat ~/.npmrc` was told to
+ * grant `../../home/.npmrc`.
+ */
+function hiddenReadsHint(
+  paths: readonly string[],
+  walled: readonly string[],
+  within: string,
+): SandboxViolation {
   const shown = paths.slice(0, 5).join(', ')
   const more = paths.length > 5 ? ` and ${paths.length - 5} more` : ''
+  const project = toRealPath(within)
+  const deny = walled.map(toRealPath)
+  const grantable = paths.find((p) => !deny.some((w) => atOrUnder(p, w) && !atOrUnder(project, w)))
+  const said =
+    `vx: the sandbox hid paths outside the project that exist on this machine, which are ` +
+    `not reported as violations: ${shown}${more}.`
   return {
     timestamp: new Date(),
     hint: true,
     line:
-      `vx: the sandbox hid paths outside the project that exist on this machine, which are ` +
-      `not reported as violations: ${shown}${more}. If the task reads one, grant it, e.g. ` +
-      `\`allow: { read: [${jsString(path.relative(toRealPath(within), paths[0]!))}] }\`.`,
+      grantable === undefined
+        ? `${said} They are walled on purpose, so vx suggests no grant for them.`
+        : `${said} If the task reads one, grant it, e.g. ` +
+          `\`allow: { read: [${jsString(grantSpelling(grantable, walled, within))}] }\`.`,
   }
 }
 
+/**
+ * A path as a committed config spells its grant: from the project inside
+ * the walls (the absolute path holds only on the machine that printed
+ * it), `~/…` under home, else absolute.
+ */
+function grantSpelling(p: string, walled: readonly string[], within: string): string {
+  const home = toRealPath(os.homedir())
+  return walled.some((w) => atOrUnder(p, toRealPath(w)))
+    ? path.relative(toRealPath(within), p) || '.'
+    : atOrUnder(p, home)
+      ? `~${p.slice(home.length)}`
+      : p
+}
+
 /**
  * Is `dir` inside a path the sandbox granted for reading? bwrap binds and
  * seatbelt rules are both prefix-based, so a grant covers the subtree.