@vzn/vx 0.0.646 → 0.0.649

package/src/orchestrator/sandbox-fix.ts

@@ -9,7 +9,7 @@ import path from 'node:path'
 import type { SandboxViolation } from '../exec/index.js'
 import type { TaskOutcome } from '../graph/index.js'
 import { isLiteralPattern } from '../util/index.js'
-import { CREDENTIAL_STORES } from './sandbox-request.js'
+import { credentialStorePaths } from './sandbox-request.js'
 
 /** Grants to add under `exec.sandbox.allow`, each list sorted and unique. */
 type SandboxFix = NonNullable<TaskOutcome['sandboxFix']>
@@ -22,9 +22,7 @@ type Kind = Exclude<keyof SandboxFix, 'withheld' | 'inputs'>
 function isCredential(abs: string): boolean {
   const base = path.basename(abs)
   if (base === '.env' || base.startsWith('.env.')) return true
-  const rel = path.relative(os.homedir(), abs)
-  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return false
-  return CREDENTIAL_STORES.some((d) => rel === d || rel.startsWith(d + path.sep))
+  return credentialStorePaths(os.homedir()).some((d) => abs === d || abs.startsWith(d + path.sep))
 }
 
 /**
@@ -33,7 +31,8 @@ function isCredential(abs: string): boolean {
  */
 function grantPath(abs: string, projectDir: string): string {
   const rel = path.relative(projectDir, abs)
-  if (rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel)) return rel
+  if (rel === '') return '.'
+  if (!rel.startsWith('..') && !path.isAbsolute(rel)) return rel
   const home = os.homedir()
   return abs.startsWith(home + path.sep) ? `~/${abs.slice(home.length + 1)}` : abs
 }
@@ -111,6 +110,9 @@ export function sandboxFix(
     else if (kind === 'read') {
       const grant = grantPath(v.path, projectDir)
       fix.read.add(grant)
+      // The link the task opened lies in a directory the sandbox lacks: the
+      // target alone stays unreachable, and the fix named it again forever.
+      if (v.via !== undefined) fix.read.add(grantPath(v.via, projectDir))
       if (keyed !== undefined && inProject(grant) && !keyed(grant)) fix.inputs.add(grant)
     } else {
       const isDir =

package/src/orchestrator/sandbox-request.ts

@@ -45,7 +45,7 @@ export interface SandboxArmer {
   readonly armed: boolean
 }
 
-/** What the run's sandbox union reads of a task: a `TaskNode`, or an agent's order. */
+/** What the run's sandbox union reads of a task: a `TaskNode`, or a worker's order. */
 export interface SandboxedNode {
   readonly config: { readonly exec?: { readonly sandbox?: ExecConfig['sandbox'] } }
 }
@@ -167,7 +167,7 @@ export function prepareSandbox(nodes: Iterable<SandboxedNode>): SandboxArmer | n
  * The sandbox half of an `ExecuteRequest` for one task, shared by the
  * cached path (through the executor) and the persistent path (spawned here).
  *
- * The user's grants derive NOTHING from `cache` (owner, 2026-09-05). Those
+ * The user's grants derive NOTHING from `cache` (2026-09-05). Those
  * are two different questions: `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
@@ -209,6 +209,15 @@ export async function sandboxRequestFor(
         `pattern, not a name — rename the directory, or run the task without exec.sandbox`,
     )
   }
+  // The runtime reports a refused touch one line per record: a path holding
+  // a line break arrived split, and an undeclared write to the project's own
+  // file was judged as outside it, with the wrong hint.
+  if (/[\n\r]/.test(home)) {
+    throw new UserError(
+      `exec.sandbox: ${home} holds a line break, which the sandbox runtime's reports cannot ` +
+        `carry, so a refused touch is misreported — rename the directory, or run the task without exec.sandbox`,
+    )
+  }
   // Bun's realpath throws ENOENT on a path holding a backslash, and SRT
   // mounts no path it cannot resolve: the task saw no project and ran in
   // $HOME.
@@ -226,7 +235,7 @@ 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) — when the key
+  // own `package.json` depends on (2026-09-05) — when the key
   // moves with it.
   const links = await linkedDeps(depDirs, node.projectDir, workspaceRoot, keyed)
   depDirs.push(...links.granted)
@@ -235,8 +244,10 @@ export async function sandboxRequestFor(
   // 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 walls = [
-    ...nested,
+  // The repository's and vx's own walls are sealed: no write grant may
+  // reach inside them either. A nested project is not: a grant into it is
+  // as explicit as one into a sibling.
+  const sealed = [
     path.join(workspaceRoot, '.git'),
     path.join(workspaceRoot, '.vx', 'cache'),
     ...(cacheDir !== undefined &&
@@ -244,6 +255,7 @@ export async function sandboxRequestFor(
       ? [cacheDir]
       : []),
   ].map(toRealPath)
+  const walls = [...nested.map(toRealPath), ...sealed]
   const resolved = resolveSandboxConfig(sandbox, node.projectDir, walls)
   // Made before the walls judge the binds: a directory grant naming nothing
   // yet (`dist/`, `dist/**`) was judged as a file, its bind its parent, and
@@ -251,7 +263,7 @@ export async function sandboxRequestFor(
   const placeholders = await prepareOutputsForBind(node.projectDir, sandbox.allow?.write ?? [])
   let config: ResolvedSandboxConfig
   try {
-    config = wallOff(resolved, workspaceRoot, walls)
+    config = wallOff(resolved, workspaceRoot, walls, sealed)
   } catch (err) {
     await sweepPlaceholders(placeholders)
     throw err
@@ -276,6 +288,7 @@ export async function sandboxRequestFor(
     baseDenyRead: [
       ...(process.platform === 'darwin' ? [workspaceRoot, ...walls] : [workspaceRoot]),
       ...(await credentialStores(workspaceRoot, config.allowWrite)),
+      ...(await vxStores(workspaceRoot, config.allowWrite, cacheDir)),
     ],
     // …but only denials INSIDE the project are worth reporting. A task
     // bumping into the wall is the sandbox working, not a finding: the
@@ -431,7 +444,7 @@ async function linkedDeps(
  */
 export function withheldLinkLine(taskId: string, w: WithheldLink): string {
   return (
-    `vx: ${taskId} read \`${w.target}\` through \`${w.link}\`, and its key folds no task of ` +
+    `vx: ${taskId} read \`${w.target}\` through \`${w.link}\`, and its key includes 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 ` +
@@ -540,20 +553,23 @@ async function fileOnPath(from: string, to: string): Promise<string> {
  * 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. A glob's
+ * refused, as there is no writable bind that leaves a wall out. One
+ * inside a sealed wall (`.git/hooks/`, vx's store) is refused too: a
+ * hook planted there runs unsandboxed at the next commit. A glob's
  * hits already stop at the walls (`resolveSandboxConfig` takes them).
  */
 function wallOff(
   config: ResolvedSandboxConfig,
   workspaceRoot: string,
   walls: readonly string[],
+  sealed: readonly string[],
 ): ResolvedSandboxConfig {
   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 (!atOrUnder(bind, home)) continue
-    const wall = walls.find((w) => atOrUnder(w, bind))
+    const wall = walls.find((w) => atOrUnder(w, bind)) ?? sealed.find((w) => atOrUnder(bind, w))
     if (wall === undefined) continue
     throw new UserError(
       `exec.sandbox.allow.write: the grant binding ${bind} would make ${wall} writable — another ` +
@@ -674,8 +690,23 @@ export const CREDENTIAL_STORES = [
   '.codex/auth.json',
 ]
 
-/** The stores present on this host, learned once per home. */
-let presentStores: { home: string; paths: string[] } | undefined
+/**
+ * Each store's path: under `home`, and again where `$XDG_CONFIG_HOME` or
+ * `$XDG_DATA_HOME` moves a `.config` or `.local/share` one. A task sees
+ * both, so a CLI reads its login there. A relative value is no XDG path.
+ */
+export function credentialStorePaths(home: string): string[] {
+  const moved = [
+    ['.config/', process.env['XDG_CONFIG_HOME']],
+    ['.local/share/', process.env['XDG_DATA_HOME']],
+  ] as const
+  const out = new Set(CREDENTIAL_STORES.map((rel) => path.join(home, rel)))
+  for (const rel of CREDENTIAL_STORES)
+    for (const [prefix, dir] of moved)
+      if (dir !== undefined && path.isAbsolute(dir) && rel.startsWith(prefix))
+        out.add(path.join(dir, rel.slice(prefix.length)))
+  return [...out]
+}
 
 /**
  * The credential stores to deny, less any that holds the workspace, and
@@ -689,19 +720,38 @@ async function credentialStores(
   workspaceRoot: string,
   writes: readonly string[],
 ): Promise<string[]> {
-  const home = homedir()
-  if (presentStores?.home !== home) {
-    presentStores = {
-      home,
-      paths: CREDENTIAL_STORES.map((rel) => path.join(home, rel)).filter((p) => existsSync(p)),
-    }
-  }
-  const stores = presentStores.paths.filter(
-    (p) => workspaceRoot !== p && !workspaceRoot.startsWith(p + path.sep),
+  // Asked per task, never memoized: an unsandboxed task earlier in the run
+  // (`npm config set` writing a token) makes a store the first sandboxed
+  // task did not see, and a refusal is never decided from a memo.
+  const stores = credentialStorePaths(homedir()).filter(
+    (p) => existsSync(p) && workspaceRoot !== p && !workspaceRoot.startsWith(p + path.sep),
   )
   return (await Promise.all(stores.map((p) => denyAround(toRealPath(p), writes)))).flat()
 }
 
+/**
+ * vx's own stores outside the workspace: `~/.vx`, which holds every
+ * repository's shared store (`resolveStoreRoot`), and a cache directory
+ * configured outside it. The rest of home stays readable, so without this
+ * a task with no grant read every project's cached outputs, around the
+ * cross-project wall and its own key. One inside the workspace is denied
+ * with it already.
+ */
+async function vxStores(
+  workspaceRoot: string,
+  writes: readonly string[],
+  cacheDir: string | undefined,
+): Promise<string[]> {
+  const root = toRealPath(workspaceRoot)
+  // HOME first, as `resolveStoreRoot` reads it.
+  const home = process.env['HOME'] || homedir()
+  const stores = [path.join(home, '.vx'), ...(cacheDir === undefined ? [] : [cacheDir])]
+    .filter((p) => existsSync(p))
+    .map(toRealPath)
+    .filter((p) => !atOrUnder(root, p) && !atOrUnder(p, root))
+  return (await Promise.all(stores.map((p) => denyAround(p, writes)))).flat()
+}
+
 /** `dir` denied, or its entries no write grant lies under or at when one is inside it. */
 async function denyAround(dir: string, writes: readonly string[]): Promise<string[]> {
   const inside = writes.filter((w) => atOrUnder(w, dir))

package/src/orchestrator/shell-verdict.ts

@@ -22,7 +22,7 @@ export function shellVerdict(args: {
   cwd: string
   bins: string[]
   /** The signal that killed the child when the runner saw one (`RunResult.signal`). */
-  signal?: string | undefined
+  signal?: string | number | undefined
   /** A sandboxed task's view: whether a file is hidden from it (no grant reads it). */
   hidden?: ((file: string) => boolean) | undefined
 }): string | undefined {
@@ -84,7 +84,10 @@ function fileVerdict(file: string): string {
 }
 
 /** The signal behind an exit above 128, from the runner's own report or the code alone. */
-function signalVerdict(code: number, signal: string | undefined): string | undefined {
+function signalVerdict(code: number, signal: string | number | undefined): string | undefined {
+  if (typeof signal === 'number') {
+    return `[vx] exit ${code} is how the shell reports a death by signal ${signal}: the process was killed by that signal`
+  }
   const signals = osConstants.signals as Partial<Record<string, number>>
   let name: string | undefined
   let num: number | undefined
@@ -96,9 +99,6 @@ function signalVerdict(code: number, signal: string | undefined): string | undef
     num = code - 128
   }
   if (name === undefined || num === undefined) return undefined
-  // A SIGINT/SIGTERM the runner saw is a shutdown or an outside stop, and
-  // the orchestrator reverts the task to aborted — that path has its own line.
-  if (signal !== undefined && (signal === 'SIGINT' || signal === 'SIGTERM')) return undefined
   const why = SIGNAL_WHY[name] ?? 'the process was killed by that signal'
   const how =
     signal !== undefined

package/src/orchestrator/signals.ts

@@ -15,7 +15,13 @@
 
 import { signalExitCode } from '../exec/index.js'
 import { claimExitForSignal, hangupIgnored, killGraceMs, settleWithin } from '../util/index.js'
-import { holdGroups, killTree, untilGroupsGone } from '../exec/index.js'
+import {
+  holdGroups,
+  killTree,
+  pauseTree,
+  restoreTerminalModes,
+  untilGroupsGone,
+} from '../exec/index.js'
 import type { Logger } from '../report/index.js'
 
 /**
@@ -135,6 +141,9 @@ export function forwardSignals(args: {
       // teardown must not throw on the way out
     }
     for (const child of everyChild()) killTree(child, 'SIGKILL')
+    // The runner restores a task's terminal modes when the task exits,
+    // which this exit does not wait for.
+    restoreTerminalModes()
     try {
       args.cache.close()
     } catch {
@@ -177,17 +186,33 @@ export function forwardSignals(args: {
   const onSigint = (): void => onSignal('SIGINT')
   const onSigterm = (): void => onSignal('SIGTERM')
   const onSighup = (): void => onSignal('SIGHUP')
+  // Ctrl-Z stops the terminal's foreground group, which is vx's alone: a
+  // task runs in its own session. vx stopped and its tasks ran on, an
+  // interactive one still reading the terminal the shell had taken back.
+  // So vx stops each task's group, then itself; `fg` or `bg` continues vx,
+  // and vx continues them.
+  const onSigtstp = (): void => {
+    for (const child of everyChild()) pauseTree(child, 'SIGSTOP')
+    process.kill(process.pid, 'SIGSTOP')
+  }
+  const onSigcont = (): void => {
+    for (const child of everyChild()) pauseTree(child, 'SIGCONT')
+  }
   if (args.enabled) {
     process.on('SIGINT', onSigint)
     process.on('SIGTERM', onSigterm)
     // A hang-up vx was started deaf to (nohup) stays ignored.
     if (!hangupIgnored()) process.on('SIGHUP', onSighup)
+    process.on('SIGTSTP', onSigtstp)
+    process.on('SIGCONT', onSigcont)
   }
   return {
     remove: () => {
       process.off('SIGINT', onSigint)
       process.off('SIGTERM', onSigterm)
       process.off('SIGHUP', onSighup)
+      process.off('SIGTSTP', onSigtstp)
+      process.off('SIGCONT', onSigcont)
     },
   }
 }

package/src/orchestrator/stable-keys.ts

@@ -57,6 +57,8 @@ export interface DeriveStableKeysArgs {
    * execute-task reuses the key when the live upstream matches.
    */
   groupKeys?: Map<string, UpfrontGroupKey>
+  /** Filled with every key the walk makes, in the order it makes them (`RunDerivation`). */
+  keys?: Map<string, string>
 }
 
 export interface StableKey {
@@ -79,7 +81,7 @@ export interface StableKey {
 export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<StableKey[]> {
   const order = topoOrder(args.nodes)
   const late = probesAfterWrites(args.nodes, args.workspaceRoot)
-  const keyById = new Map<string, string>()
+  const keyById = args.keys ?? new Map<string, string>()
   const unstableById = new Set<string>()
   // Transitive-upstream output producers, accumulated in topo order — the
   // inputs to the stability gate. A task's key is preliminary if an upstream
@@ -338,6 +340,90 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
   return stableKeys
 }
 
+/**
+ * The keys `deriveStableKeys` would make, from a derivation under the same
+ * graph, configs and ignored outputs (`readRunDelta`): every task's key
+ * is the one remembered unless it is `dirty`, and a dirty task's is derived
+ * as the walk derives it, over its deps' keys, in the walk's order. Which
+ * tasks are stable and which uncached keys are kept are the remembered
+ * verdicts: they read only what the global token names. `keys` is updated
+ * in place.
+ */
+export async function rederiveKeys(
+  args: Omit<DeriveStableKeysArgs, 'keys' | 'groupKeys'>,
+  keys: Map<string, string>,
+  dirty: ReadonlySet<string>,
+): Promise<void> {
+  for (const [id] of keys) {
+    if (!dirty.has(id)) continue
+    const node = args.nodes.get(id)!
+    const upstream = synthUpstream(node, args.nodes, keys)
+    keys.set(
+      id,
+      isGroupTask(node) && node.config.inputs === undefined
+        ? computeGroupHash(upstream)
+        : await computeTaskHash({
+            node,
+            upstream,
+            workspaceRoot: args.workspaceRoot,
+            cache: args.cache,
+            forwardArgs: args.forwardArgs,
+            nestedProjectDirs: args.nestedDirsByProject.get(node.projectName) ?? [],
+            gitFilesCache: args.gitFilesCache,
+            hashCache: args.hashCache,
+          }),
+    )
+  }
+}
+
+/**
+ * A project's positive outputs indexed by literal head, so a reader finds
+ * the ones its inputs reach (`workspaceInputsReach`: a head equal to, above
+ * or below an input's) without testing each: one project of 9000 tasks
+ * tested 81 million pairs, 6 s of a plan (2026-10-25).
+ */
+class ProjectOutputs {
+  private readonly globs: string[] = []
+  private readonly byHead = new Map<string, number[]>()
+  private sorted: string[] | undefined
+
+  add(glob: string, head: string): void {
+    const key = head === '.' ? '' : head
+    let at = this.byHead.get(key)
+    if (at === undefined) this.byHead.set(key, (at = []))
+    at.push(this.globs.length)
+    this.globs.push(glob)
+    this.sorted = undefined
+  }
+
+  /** The globs `inputs` reach, in the order they were added. */
+  reachedBy(inputs: readonly string[]): string[] {
+    const hit = new Set<number>()
+    const take = (head: string) => {
+      for (const i of this.byHead.get(head) ?? []) hit.add(i)
+    }
+    for (const raw of inputs) {
+      if (raw.startsWith('!')) continue
+      take('')
+      const p = literalPrefix(raw)
+      if (p === '') return [...this.globs]
+      for (let at = p.indexOf('/'); at !== -1; at = p.indexOf('/', at + 1)) take(p.slice(0, at))
+      take(p)
+      const sorted = (this.sorted ??= [...this.byHead.keys()].sort())
+      const from = `${p}/`
+      let lo = 0
+      let hi = sorted.length
+      while (lo < hi) {
+        const mid = (lo + hi) >> 1
+        if (sorted[mid]! < from) lo = mid + 1
+        else hi = mid
+      }
+      for (let i = lo; i < sorted.length && sorted[i]!.startsWith(from); i++) take(sorted[i]!)
+    }
+    return [...hit].sort((a, b) => a - b).map((i) => this.globs[i]!)
+  }
+}
+
 /**
  * The same-project outputs a reader's inputs reach, root-relative, each with
  * its project dir and project-relative glob: the outputs the gate would key
@@ -350,14 +436,13 @@ export function gatedOutputs(
   const out = new Map<string, { projectDir: string; glob: string }>()
   // Each project's positive outputs with their literal heads, read once:
   // 1,000 projects' tasks spent 5-8 ms here re-splitting the same globs.
-  const outputsOf = new Map<string, { glob: string; head: string }[]>()
+  const outputsOf = new Map<string, ProjectOutputs>()
   for (const n of nodes.values()) {
     const files = n.config.cache?.outputs.files
     if (files === undefined || files.length === 0) continue
-    let list = outputsOf.get(n.projectName)
-    if (list === undefined) outputsOf.set(n.projectName, (list = []))
-    for (const glob of files)
-      if (!glob.startsWith('!')) list.push({ glob, head: literalPrefix(glob) })
+    let po = outputsOf.get(n.projectName)
+    if (po === undefined) outputsOf.set(n.projectName, (po = new ProjectOutputs()))
+    for (const glob of files) if (!glob.startsWith('!')) po.add(glob, literalPrefix(glob))
   }
   if (outputsOf.size === 0) return out
   for (const n of nodes.values()) {
@@ -366,8 +451,7 @@ export function gatedOutputs(
     if (inputs === undefined || outputs === undefined || isGroupTask(n)) continue
     let back: string[] | undefined
     let rel: string | undefined
-    for (const { glob: o, head } of outputs) {
-      if (!workspaceInputsReach(inputs, [head])) continue
+    for (const o of outputs.reachedBy(inputs)) {
       rel ??= relPosix(workspaceRoot, n.projectDir)
       back ??= inputs.filter((g) => g.startsWith('!')).map((g) => g.slice(1))
       const rooted = rel === '' ? o : `${rel}/${o}`

package/src/orchestrator/steps.ts

@@ -1,11 +1,11 @@
 // vx's own steps (reading the lock, keying, uploads, teardown) rendered as
-// tasks (M, 2026-10-15): `vx:<step>`, and `<plugin package>:setup` /
+// tasks (2026-10-15): `vx:<step>`, and `<plugin package>:setup` /
 // `:teardown`. `:` is no task id's separator, so a step never collides with
 // a project named `vx` or a plugin package's own `#setup` task. A step is
 // not a task: no stat, history row or telemetry record counts it.
 //
 // A run shows only the steps it waits on, before its first task or its end
-// (M, 2026-10-16). One that runs beside the tasks (`vx:prefetch`) is a
+// (2026-10-16). One that runs beside the tasks (`vx:prefetch`) is a
 // `background` step: never shown, and kept for `vx last` (run-steps.ts).
 import type { Logger } from '../report/index.js'
 import type { RunStep } from './run-steps.js'

package/src/orchestrator/task-artifacts.ts

@@ -8,10 +8,12 @@ import {
   type CacheLayer,
   type ResolvedRemote,
   resolveOutputTree,
-  resolveWorkspaceOutputs,
+  resolveWorkspaceOutputTree,
+  sayRemoteFault,
 } from '../cache/index.js'
-import { secretMask } from '../util/index.js'
-import { decodeOutputLog, encodeOutputLog } from './output-log.js'
+import type { CapturedChunk } from '../exec/index.js'
+import { secretMask, thrownMessage } from '../util/index.js'
+import { decodeOutputLog, encodeOutputLog, maskedOutputLog } from './output-log.js'
 
 /** The task a `TaskArtifacts` call names: where its outputs are and what ran. */
 export interface ArtifactTask {
@@ -27,17 +29,26 @@ export interface ArtifactTask {
   }
   /** The projects inside `projectDir` (absolute), whose files are not its outputs. */
   readonly nestedProjectDirs?: readonly string[]
+  /**
+   * Files under its outputs it found and left as they were (absolute): an
+   * upstream's, which an additive task builds on, not its entry's.
+   */
+  readonly others?: ReadonlySet<string>
 }
 
 /** What a task's run left besides its files: its output, and its time and usage. */
 export interface ArtifactRun {
-  readonly stdout: string
-  readonly stderr: string
+  /** Both streams in the order they were written, as a `BoundedCapture` keeps them. */
+  readonly output: readonly CapturedChunk[]
   readonly durationMs: number
   readonly cpuMs?: number
   readonly peakRssBytes?: number
   /** Its environment: a secret value in it is masked out of the stored output. */
   readonly env?: Readonly<Record<string, string | undefined>>
+  /** Its `exec.env.secret`: names in `env` whose values are masked whatever the name. */
+  readonly secret?: readonly string[]
+  /** No remote held the key when the run asked: its upload asks none first. */
+  readonly absent?: boolean
 }
 
 export interface TaskArtifacts {
@@ -50,41 +61,66 @@ export interface TaskArtifacts {
   save(key: string, task: ArtifactTask, run: ArtifactRun): Promise<void>
   /**
    * Lays entry `key`'s files into the workspace, from the local store or
-   * else the first remote holding it, and resolves its output; null when
+   * else the first remote holding it, and resolves its output, both streams
+   * in the order written; null when
    * none holds it. A key restored here and then saved is not uploaded
    * again.
    */
-  restore(key: string, task: ArtifactTask): Promise<{ stdout: string; stderr: string } | null>
+  restore(key: string, task: ArtifactTask): Promise<CapturedChunk[] | null>
+  /**
+   * Entry `key`'s output alone, laying no file; null when no cache holds
+   * it. An `exec.remote: 'only'` task's files stay off this disk.
+   */
+  output(key: string): Promise<CapturedChunk[] | null>
+  /**
+   * True once a remote the run reads holds entry `key`, this machine's
+   * entry uploaded to those it writes when none does: another machine of
+   * the run reads the remotes alone. False when none holds it and none took it.
+   */
+  share(key: string): Promise<boolean>
+  /**
+   * This machine's entry `key` uploaded over each written remote's copy,
+   * which another machine of the run found corrupt. True when one took it.
+   */
+  resend(key: string): Promise<boolean>
+  /**
+   * Whether a remote the workspace writes took entry `key` when `save`
+   * uploaded it; undefined when it writes none. Another machine of the
+   * run reads the remotes alone, so false there means only this one has it.
+   */
+  uploaded?(key: string): Promise<boolean | undefined>
 }
 
 export function taskArtifacts(cache: CacheLayer, workspaceRoot: string): TaskArtifacts {
   return {
     async save(key, task, run) {
-      const [tree, wsFiles] = await Promise.all([
+      const [tree, wsTree] = await Promise.all([
         resolveOutputTree({
           projectDir: task.projectDir,
           outputs: task.outputs.files,
           nestedProjectDirs: [...(task.nestedProjectDirs ?? [])],
         }),
-        resolveWorkspaceOutputs({ workspaceRoot, outputs: task.outputs.workspaceFiles }),
-      ])
-      const mask = secretMask([process.env, run.env ?? {}])
-      const log = encodeOutputLog([
-        { text: run.stdout, err: false },
-        { text: run.stderr, err: true },
+        resolveWorkspaceOutputTree({ workspaceRoot, outputs: task.outputs.workspaceFiles }),
       ])
+      const mine = (f: string) => task.others?.has(f) !== true
+      const files = tree.files.filter(mine)
+      const ws = wsTree.files.filter(mine)
+      const mask = secretMask([process.env, run.env ?? {}], run.secret)
+      const log = mask === null ? encodeOutputLog(run.output) : maskedOutputLog(run.output, mask)
       await cache.save({
         hash: key,
         projectDir: task.projectDir,
-        outputFiles: tree.files,
+        outputFiles: files,
         ...(tree.emptyDirs.length > 0 ? { outputDirs: tree.emptyDirs } : {}),
         workspaceRoot,
-        ...(wsFiles.length > 0 ? { workspaceOutputFiles: wsFiles } : {}),
+        ...(ws.length > 0 ? { workspaceOutputFiles: ws } : {}),
+        ...(wsTree.emptyDirs.length > 0 ? { workspaceOutputDirs: wsTree.emptyDirs } : {}),
+        ...(run.absent === true ? { absent: true } : {}),
         entry: {
           taskId: task.id,
           command: mask?.mask(task.command) ?? task.command,
           durationMs: run.durationMs,
-          stdout: mask?.mask(log) ?? log,
+          stdout: log,
           ...(run.cpuMs !== undefined ? { cpuMs: run.cpuMs } : {}),
           ...(run.peakRssBytes !== undefined ? { peakRssBytes: run.peakRssBytes } : {}),
         },
@@ -96,14 +132,17 @@ export function taskArtifacts(cache: CacheLayer, workspaceRoot: string): TaskArt
       const entry = await (cache.getSaved ? cache.getSaved(key) : cache.get(key))
       if (entry === null) return null
       await cache.restoreOutputs(key, task.projectDir, workspaceRoot, task.outputs)
-      let stdout = ''
-      let stderr = ''
-      for (const c of decodeOutputLog(entry.stdout)) {
-        if (c.err) stderr += c.text
-        else stdout += c.text
-      }
-      return { stdout, stderr }
+      return decodeOutputLog(entry.stdout)
     },
+
+    async output(key) {
+      const entry = await (cache.getSaved ? cache.getSaved(key) : cache.get(key))
+      return entry === null ? null : decodeOutputLog(entry.stdout)
+    },
+
+    share: (key) => cache.share?.(key) ?? Promise.resolve(false),
+    resend: (key) => cache.resend?.(key) ?? Promise.resolve(false),
+    uploaded: (key) => cache.uploaded?.(key) ?? Promise.resolve(undefined),
   }
 }
 
@@ -122,7 +161,7 @@ export interface CacheFacts {
   readonly expiresAt?: number
 }
 
-/** The run's `CacheFacts`: each readable remote's `lend`, asked now; one that throws lends nothing. */
+/** The run's `CacheFacts`: each readable remote's `lend`, asked now; one that throws lends nothing, said. */
 export async function cacheFacts(
   remotes: readonly ResolvedRemote[],
   refs: readonly string[],
@@ -132,7 +171,32 @@ export async function cacheFacts(
   await Promise.all(
     remotes.map(async (r) => {
       if (r.plugin === undefined || r.remote.lend === undefined || !r.read) return
-      const got = await r.remote.lend().catch(() => undefined)
+      // Through a promise, and checked: a plugin's synchronous throw skipped
+      // the catch and rejected every remote's answer, and a `null` or a
+      // numeric token met `.token` as a TypeError.
+      const got = await Promise.resolve()
+        .then(() => r.remote.lend!())
+        .then((answer: unknown) => {
+          if (answer === undefined) return undefined
+          if (typeof answer !== 'object' || answer === null)
+            throw new Error(
+              `it answered ${answer === null ? 'null' : typeof answer}, not { token, expiresAt? }`,
+            )
+          const { token, expiresAt: ends } = answer as { token?: unknown; expiresAt?: unknown }
+          if (typeof token !== 'string') throw new Error('it answered a token that is not a string')
+          if (ends !== undefined && !(typeof ends === 'number' && Number.isFinite(ends)))
+            throw new Error('it answered an expiresAt that is not a time in ms')
+          return { token, ...(ends === undefined ? {} : { expiresAt: ends }) }
+        })
+        .catch((err: unknown) => {
+          // Said: unsaid, the run's workers went without this remote and no line said why.
+          const message = thrownMessage(err)
+          sayRemoteFault(
+            r,
+            new Error(`lend of ${r.plugin}'s access failed: ${message}`, { cause: err }),
+          )
+          return undefined
+        })
       if (got === undefined) return
       lent[r.plugin] = got.token
       if (got.expiresAt !== undefined) expiresAt = Math.min(expiresAt ?? Infinity, got.expiresAt)