@vzn/vx 0.0.491 → 0.0.492

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.491",
+  "version": "0.0.492",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.491",
-    "@vzn/vx-linux-arm64": "0.0.491",
-    "@vzn/vx-darwin-x64": "0.0.491",
-    "@vzn/vx-darwin-arm64": "0.0.491"
+    "@vzn/vx-linux-x64": "0.0.492",
+    "@vzn/vx-linux-arm64": "0.0.492",
+    "@vzn/vx-darwin-x64": "0.0.492",
+    "@vzn/vx-darwin-arm64": "0.0.492"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/index.ts

@@ -16,6 +16,7 @@ export {
   type InvocationRecord,
   KEYED_RUNS_SQL,
   parseCachePolicy,
+  scopeCachePolicy,
   type RunRecord,
   type TaskInputRow,
   WORKSPACE_OUTPUT_PREFIX,

package/src/cache/layered-cache.ts

@@ -33,6 +33,7 @@ import type {
   SaveArgs,
 } from './cache.js'
 import { FULL_CACHE_POLICY, type OutputDirRow } from './cache.js'
+import { xxh3hex } from '../util/index.js'
 
 /**
  * What a remote cache layer must provide — THE plugin seam for remote
@@ -157,6 +158,68 @@ function batchOf(hashes: readonly string[]): { batch: string } {
   return { batch: `of ${hashes.length} artifact${hashes.length === 1 ? '' : 's'}` }
 }
 
+/**
+ * The remote as an untrusted scope sees it: reads try the scope's key,
+ * where a PR's own earlier runs left it, then the trusted one; writes go to the scope's key only. A scope's key is
+ * derived from the task key, so every wire stores it unchanged and the
+ * trusted keyspace never holds a scoped write. What a scoped read
+ * returns is ingested under the TASK key, and ingest refuses an artifact
+ * recording another key, so a derived-key collision degrades to a miss.
+ */
+class ScopedRemote implements RemoteCacheLayer {
+  readonly endpoint?: string
+  readonly hasMany?: (hashes: readonly string[]) => Promise<Set<string> | null>
+  /** Task keys a batch probe found under the trusted key alone: their GET skips the scope's. */
+  private readonly trustedOnly = new Set<string>()
+
+  constructor(
+    private readonly remote: RemoteCacheLayer,
+    private readonly scope: string,
+  ) {
+    if (remote.endpoint !== undefined) this.endpoint = remote.endpoint
+    if (remote.hasMany !== undefined) this.hasMany = (hashes) => this.scopedHasMany(hashes)
+  }
+
+  private scoped(hash: string): string {
+    return scopedKey(this.scope, hash)
+  }
+
+  async has(hash: string): Promise<boolean> {
+    return (await this.remote.has(this.scoped(hash))) || this.remote.has(hash)
+  }
+
+  private async scopedHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
+    const scoped = hashes.map((h) => this.scoped(h))
+    const [trusted, own] = await Promise.all([
+      this.remote.hasMany!(hashes),
+      this.remote.hasMany!(scoped),
+    ])
+    if (trusted == null || own == null) return null
+    const found = new Set(trusted)
+    for (let i = 0; i < hashes.length; i++) {
+      if (own.has(scoped[i]!)) found.add(hashes[i]!)
+      else if (trusted.has(hashes[i]!)) this.trustedOnly.add(hashes[i]!)
+    }
+    return found
+  }
+
+  async get(
+    hash: string,
+  ): Promise<{ body: Blob | Response; durationMs: number | undefined } | null> {
+    if (this.trustedOnly.has(hash)) return this.remote.get(hash)
+    return (await this.remote.get(this.scoped(hash))) ?? this.remote.get(hash)
+  }
+
+  put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void> {
+    return this.remote.put(this.scoped(hash), body, meta)
+  }
+}
+
+/** The key an untrusted scope stores `hash` under: task-key shaped, 16 hex. */
+function scopedKey(scope: string, hash: string): string {
+  return xxh3hex(`vx-cache-scope\0${scope}\0${hash}`)
+}
+
 export interface LayeredCacheOptions {
   /**
    * Called for the remote failures the layer degrades to a miss, once per
@@ -222,12 +285,17 @@ export class LayeredCache implements CacheLayer {
    */
   private readonly reported = new Map<string, { cause: string; repeats: number }>()
 
+  /** The remote as this run's scope sees it: `remote` itself when trusted. */
+  private readonly wire: RemoteCacheLayer
+
   constructor(
     readonly local: Cache,
     private readonly remote: RemoteCacheLayer,
     private readonly options: LayeredCacheOptions = {},
   ) {
     this.policy = options.policy ?? FULL_CACHE_POLICY
+    const scope = this.policy.remoteScope
+    this.wire = scope === undefined ? remote : new ScopedRemote(remote, scope)
     this.endpoint = printableEndpoint(remote.endpoint)
   }
 
@@ -254,11 +322,11 @@ export class LayeredCache implements CacheLayer {
    * degrades to "no batch info" and the caller falls back to per-hash.
    */
   async remoteHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
-    if (!this.policy.remoteRead || this.remote.hasMany === undefined) return null
+    if (!this.policy.remoteRead || this.wire.hasMany === undefined) return null
     try {
       // `return await`, deliberately: the catch below is the never-fail
       // contract, and a returned promise's rejection would sail past it.
-      const found: unknown = await this.remote.hasMany(hashes)
+      const found: unknown = await this.wire.hasMany(hashes)
       if (found !== null && found !== undefined && !(found instanceof Set)) {
         this.reportRemoteError(
           'probe',
@@ -337,7 +405,7 @@ export class LayeredCache implements CacheLayer {
     if ((await this.local.has(hash)) === 'local') return 'local'
     if (!this.policy.remoteRead) return null
     try {
-      return (await this.remote.has(hash)) ? 'remote' : null
+      return (await this.wire.has(hash)) ? 'remote' : null
     } catch (err) {
       this.reportRemoteError('probe', hash, err)
       return null
@@ -373,7 +441,7 @@ export class LayeredCache implements CacheLayer {
 
     let remoteResult: unknown
     try {
-      remoteResult = await this.remote.get(hash)
+      remoteResult = await this.wire.get(hash)
     } catch (err) {
       this.reportRemoteError('download', hash, err)
       return false
@@ -478,7 +546,7 @@ export class LayeredCache implements CacheLayer {
       try {
         const body =
           packed !== undefined ? new Blob([packed]) : Bun.file(this.local.outputsPath(hash))
-        await this.remote.put(hash, body, { durationMs })
+        await this.wire.put(hash, body, { durationMs })
       } catch (err) {
         this.reportRemoteError('upload', hash, err)
       }

package/src/cache/policy.ts

@@ -20,6 +20,12 @@ export interface CachePolicy {
   localWrite: boolean
   remoteRead: boolean
   remoteWrite: boolean
+  /**
+   * An untrusted scope (`cacheScope: 'pr-123'`): remote reads try this
+   * scope's keys, then the trusted ones; remote writes go to this scope's
+   * keys only. Absent = trusted. See {@link scopeCachePolicy}.
+   */
+  remoteScope?: string
 }
 
 /** All four axes on — the default when no cache flag is passed. */
@@ -84,3 +90,17 @@ export function parseCachePolicy(spec: string, base: CachePolicy = FULL_CACHE_PO
   }
   return out
 }
+
+/**
+ * Apply a workspace's `cacheScope` to the run's policy. `'trusted'` (or
+ * none) changes nothing; `'read-only'` turns remote writes off; any other
+ * name is an untrusted scope. A clamp, never a widening: `--cache` still
+ * decides which axes are on. A client-side convention, not a boundary —
+ * any run holding a write credential can write a trusted key; only the
+ * cache server, by token, can refuse it (docs/security.md).
+ */
+export function scopeCachePolicy(policy: CachePolicy, scope: string | undefined): CachePolicy {
+  if (scope === undefined || scope === 'trusted') return policy
+  if (scope === 'read-only') return { ...policy, remoteWrite: false }
+  return { ...policy, remoteScope: scope }
+}

package/src/cli/run.ts

@@ -1,5 +1,6 @@
 import { appendFileSync, mkdirSync } from 'node:fs'
 import path from 'node:path'
+import { isatty } from 'node:tty'
 import { translateForeign } from './foreign-flags.js'
 import { flagHint, seeHelp } from './help.js'
 import { defaultAffectedBase, findWorkspaceRoot } from '../workspace/index.js'
@@ -422,6 +423,11 @@ export function detectFlow(
     : 'focused'
 }
 
+/** `CI=0` / `CI=false` are not CI, as the output flow reads them. */
+function onCI(v: string | undefined): boolean {
+  return v !== undefined && v !== '' && v !== '0' && v !== 'false'
+}
+
 /**
  * Resolve parsed `vx run` argv into the `RunOptions` the orchestrator
  * consumes. Shared between `runCmd` and `watchCmd` so both subcommands
@@ -535,12 +541,20 @@ export async function resolveRunOptions(
     tasks: [...tasks],
     cache: parsed.cache,
     ...(parsed.remoteRequested ? { remoteRequested: true } : {}),
+    // A laptop reads the shared cache and never writes it (owner,
+    // 2026-10-03); naming the remote in `--cache` is asking to.
+    ...(!parsed.remoteRequested && !onCI(process.env['CI'])
+      ? { defaultCacheScope: 'read-only' }
+      : {}),
     flow: detectFlow(parsed),
     ...(parsed.frozen ? { frozen: true } : {}),
     ...(parsed.outputLogs !== undefined ? { outputLogs: parsed.outputLogs } : {}),
     ...(parsed.download !== undefined ? { download: parsed.download } : {}),
     ...(parsed.continueMode !== undefined ? { continueMode: parsed.continueMode } : {}),
     forwardArgs: parsed.forwardArgs,
+    // isatty, not process.stdin: touching the stream opens it, and a config
+    // that throws then reports an extra native stack frame.
+    ...(isatty(0) ? { tty: true } : {}),
   }
   if (parsed.excludeDependencies === 'all') {
     opts.excludeDependencies = 'all'

package/src/config.ts

@@ -29,6 +29,19 @@ export interface WorkspaceConfig {
    * HEAD, else `HEAD~1`. Never folded into a cache key.
    */
   affectedBase?: string
+  /**
+   * Where this run's remote cache writes land. `'trusted'` reads and
+   * writes the trusted keys, for the default branch's CI. `'read-only'`
+   * reads them and writes nothing; omitted, `vx run` off CI takes it, and
+   * on CI (or with `--cache` naming the remote) `'trusted'`. Any other
+   * name (`'pr-123'`) is an untrusted scope: reads try the scope's keys,
+   * then the trusted ones, and writes go to the scope's only, so a PR never
+   * writes what the default branch reads. A client-side convention, not a
+   * security boundary: only a cache server that scopes writes by token
+   * can refuse a run that ignores it. `VX_CACHE_SCOPE` beats it. Never
+   * folded into a cache key.
+   */
+  cacheScope?: string
   /**
    * Plugins registered for this workspace, consulted in this order once
    * per `vx run`: each fills any of the pipeline stages and capabilities
@@ -362,6 +375,16 @@ export interface ExecConfig {
    * to cache and the work continues after vx's run notion of "done".
    */
   persistent?: PersistentConfig
+  /**
+   * The task reads the terminal: a prompt, a REPL, a watch mode's keys.
+   * When vx's stdin is a TTY the task gets vx's stdin, stdout and stderr
+   * as they are, and no other task starts while it runs (a persistent one:
+   * until it is spawned). It runs in its own session, so `/dev/tty` still
+   * cannot be opened. Off a TTY (CI) it runs as any task. Always on this
+   * machine, never cached; not allowed with `cache`, `sandbox` or
+   * `persistent.readyWhen`.
+   */
+  interactive?: boolean
   /**
    * Confine this task's process: what it may read, write and reach.
    * Nothing is confined unless this is present.

package/src/exec/executor.ts

@@ -5,7 +5,8 @@
 // every executor list — what a plugin executor declines runs here.
 // Persistent tasks (`exec.persistent`) never reach an executor: they are local by
 // construction (a worker cannot hand the submitter a listening port) and
-// stay on `runPersistent`.
+// stay on `runPersistent`. An `exec.interactive` task reaches the local one
+// only: no plugin can hand it this terminal.
 //
 // Lives in `exec/` (not `orchestrator/`) so the contract depends only on
 // process primitives — the module-boundary matrix forbids `exec` → `cache`,
@@ -152,6 +153,12 @@ export interface ExecuteRequest {
   /** See `RunOptions.liveChildren`: the run's SIGINT/SIGTERM registry. */
   readonly liveChildren?: Set<ReturnType<typeof Bun.spawn>>
   readonly sandbox?: ExecuteSandbox
+  /**
+   * The task holds vx's terminal (`exec.interactive` on a TTY): its stdin,
+   * stdout and stderr are vx's own, and the callbacks hear nothing. Only
+   * core's local executor is ever handed such a task (placement.ts).
+   */
+  readonly terminal?: true
 }
 
 export interface ExecuteResult extends RunResult {

package/src/exec/local-executor.ts

@@ -45,7 +45,7 @@ export function localExecutor(): TaskExecutor {
         ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
       }
       if (req.sandbox === undefined) {
-        const res = await runCommand(common)
+        const res = await runCommand(req.terminal === true ? { ...common, terminal: true } : common)
         return { ...res, violations: [] }
       }
       return runSandboxed({

package/src/exec/runner.ts

@@ -87,6 +87,19 @@ export interface RunOptions {
    * handler can SIGTERM everything still alive mid-run.
    */
   liveChildren?: Set<ReturnType<typeof Bun.spawn>>
+  /**
+   * Hand the child vx's own stdin, stdout and stderr (`exec.interactive` on
+   * a TTY). Nothing passes through vx: the callbacks hear nothing and the
+   * result's streams are empty.
+   */
+  terminal?: boolean
+}
+
+/** A child's descriptors 0–2: vx's own for a task that holds the terminal. */
+function taskStdio(terminal: boolean | undefined, stdin: 'ignore' | 'pipe') {
+  return terminal === true
+    ? (['inherit', 'inherit', 'inherit'] as const)
+    : ([stdin, 'pipe', 'pipe'] as const)
 }
 
 export function shellQuote(arg: string): string {
@@ -492,20 +505,19 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
           // A pipe vx holds and never writes: stdin stays open while vx
           // lives and ends when it does. A dev server that exits on stdin
           // EOF (esbuild --watch, Vite's case in turborepo#8915) became ready
-          // and exited 0 under 'ignore'. Not the terminal: several servers
-          // would steal each other's keystrokes, and a CI's /dev/null stdin
-          // is the same EOF. The one-shot spawn below keeps 'ignore', so a
-          // task that reads stdin can never hang CI.
+          // and exited 0 under 'ignore'. Not the terminal unless the task
+          // asks (`terminal`, one per run): several servers would steal each
+          // other's keystrokes, and a CI's /dev/null stdin is the same EOF.
+          // The one-shot spawn below keeps 'ignore', so a task that reads
+          // stdin can never hang CI.
           stdio: [
-            'pipe',
-            'pipe',
-            'pipe',
+            ...taskStdio(opts.terminal, 'pipe'),
             ...(signalFd ? ['pipe' as const] : []),
             ...(guard === undefined ? [] : [guard]),
           ],
           // Its own session and process group, so a kill reaches what it
-          // forked (kill-tree.ts). stdin is a pipe, so a background group
-          // never stops on a terminal read.
+          // forked (kill-tree.ts). The terminal, when it is handed over, is
+          // not this session's controlling one, so no read stops the group.
           detached: true,
         },
       ),
@@ -712,10 +724,10 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
         ...SH_ARGV0,
         cwd: opts.cwd,
         env: opts.env as Record<string, string>,
-        stdio: ['ignore', 'pipe', 'pipe', ...(guard === undefined ? [] : [guard])],
+        stdio: [...taskStdio(opts.terminal, 'ignore'), ...(guard === undefined ? [] : [guard])],
         // Its own session and process group, so a kill reaches what it
-        // forked (kill-tree.ts). stdin is ignored, so a background group
-        // never stops on a terminal read.
+        // forked (kill-tree.ts). A terminal handed over is not this
+        // session's controlling one, so no read stops the group.
         detached: true,
       }),
     )
@@ -877,11 +889,8 @@ export async function streamToString(
   signal?: AbortSignal,
   retain = true,
 ): Promise<string> {
-  // Bun.spawn types stdout/stderr as `ReadableStream | number | undefined`
-  // — the `number` is for inheritance modes, only present when the caller
-  // chose `'inherit'` instead of `'pipe'`. We only call this with `'pipe'`,
-  // so the runtime value is always a ReadableStream; the `number` branch
-  // is unreachable but typed.
+  // Bun.spawn types stdout/stderr as `ReadableStream | number | undefined`;
+  // a stream the child inherited (`terminal`) is not one, and holds nothing.
   if (!stream || typeof stream === 'number') return ''
   const full = new BoundedCapture()
   const reader = stream.getReader()

package/src/graph/scheduler.ts

@@ -251,6 +251,13 @@ export interface ScheduleOptions {
    * pooled tasks hold no local resources and are never asked.
    */
   admit?: (id: string, running: ReadonlySet<string>) => boolean
+  /**
+   * Tasks that hold the terminal (`exec.interactive` on a TTY). One starts
+   * only once nothing runs, and nothing starts while it runs. When one is
+   * the next to start, dispatch stops so the running tasks drain. A
+   * persistent one holds it until `execute` resolves, at spawn.
+   */
+  exclusive?: ReadonlySet<string>
 }
 
 /**
@@ -477,7 +484,22 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
     if (pool === undefined) return execRoom()
     return (poolActive.get(pool.name) ?? 0) < pool.capacity
   }
+  const exclusive = options.exclusive
+  let holding = false
+  const busy = (): boolean => {
+    if (active > 0 || activeRestore > 0) return true
+    for (const n of poolActive.values()) if (n > 0) return true
+    return false
+  }
   const admit = (id: string): (() => void) => {
+    if (exclusive?.has(id) === true) {
+      holding = true
+      active++
+      return () => {
+        holding = false
+        active--
+      }
+    }
     if (inRestoreTier(id)) {
       activeRestore++
       return () => {
@@ -643,6 +665,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
       // task returns without asking (finishing it is free); restore
       // tasks are never asked, so they never park.
       const takeFitting = (): string | undefined => {
+        if (holding) return undefined
         // No pools, no policy and a full exec lane: nothing on the
         // exec queue can be admitted, so it is not scanned — scanning it
         // would pop and re-park every ready exec task on every tick, and
@@ -656,6 +679,11 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
             const seq = execReady.peekSeq()
             const id = execReady.pop() as string
             if (willSkip(id)) return id
+            if (exclusive?.has(id) === true) {
+              if (!busy() && (!admitActive || admits(id))) return id
+              parked.push([id, seq])
+              return undefined
+            }
             if (hasRoom(id)) {
               if (!admitActive || admits(id)) return id
               // A free worker, refused by the policy: the hold starts now.

package/src/orchestrator/execute-task.ts

@@ -227,6 +227,8 @@ export interface ExecuteArgs {
    * walk cost 1,000 read-only misses 1.62 → 1.78 s, item 750).
    */
   noDependants?: true
+  /** The task holds vx's terminal (`terminalHolders`): its stdio is vx's own. */
+  terminal?: true
 }
 
 /**
@@ -362,6 +364,7 @@ async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutcome> {
     onStderr: serverErr ? (chunk) => serverErr.push(chunk) : (chunk) => log.taskStderr(node, chunk),
     ...(args.liveChildren !== undefined ? { liveChildren: args.liveChildren } : {}),
     ...(signalChannel ? { signalChannel } : {}),
+    ...(args.terminal === true ? { terminal: true } : {}),
   }
   if (step.persistent.readyWhen !== undefined) {
     persistentOpts.readyWhen = step.persistent.readyWhen
@@ -1146,6 +1149,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       // through this flag — the policy gates above only cover vx's OWN cache.
       ...(cfgCacheable && !(policy.localRead || policy.remoteRead) ? { refresh: true } : {}),
       outputs: { files: outputs, workspaceFiles: wsOutputs },
+      ...(args.terminal === true ? { terminal: true as const } : {}),
     }
     if (!userSandbox) return base
     await args.armSandbox?.()

package/src/orchestrator/logger.ts

@@ -178,7 +178,7 @@ export function defaultLogger(
   colors: ColorSupport = detectColors(),
   view: OutputView = { mode: 'full' },
   out: StatusStream = process.stdout,
-  opts: { forceFloorMs?: number; coalesce?: boolean } = {},
+  opts: { forceFloorMs?: number; coalesce?: boolean; tty?: boolean } = {},
 ): DefaultLogger {
   // Per-task buffers, split by stream. Splitting lets the framed-output
   // renderer put stdout under `├─ stdout` and stderr under `├─ stderr`.
@@ -440,8 +440,16 @@ export function defaultLogger(
   // group (see markSurfacedDeps) — is a "primary" node the focused
   // view shows. Groups never stream (no output of their own).
   const isPrimary = (node: TaskNode): boolean => node.requested || node.surfaced === true
+  // A task handed the terminal writes to it directly, so the status region
+  // goes for good (it would repaint over a prompt) and, in the views that
+  // frame executed work, a live frame opens before it and closes after;
+  // what vx itself says about it streams inside.
+  const holdsTerminal = (node: TaskNode): boolean =>
+    opts.tty === true && node.config.exec?.interactive === true
+  const framesTerminal = view.mode === 'full' || view.mode === 'focused' || view.mode === 'broad'
   const streamsLive = (node: TaskNode): boolean =>
-    view.mode === 'focused' && isPrimary(node) && !isGroupTask(node) && requestedCount <= 1
+    (framesTerminal && holdsTerminal(node)) ||
+    (view.mode === 'focused' && isPrimary(node) && !isGroupTask(node) && requestedCount <= 1)
 
   return {
     settle() {
@@ -487,6 +495,11 @@ export function defaultLogger(
     },
     taskStart(node) {
       if (isGroupTask(node)) return
+      if (holdsTerminal(node)) {
+        killStatus()
+        // What is coalesced lands before the task writes past it.
+        writer.settle()
+      }
       // Focused flow: the status line exists for the dependency
       // phase only. The moment a requested node starts streaming,
       // clear it for good — its raw output owns the terminal now.
@@ -647,7 +660,10 @@ export function defaultLogger(
         // the terminal where a frame would have: a task that traps Ctrl-C
         // and exits 0 is aborted since item 962, and its frame was dropped
         // with the count.
-        const framed = view.mode === 'full' || (view.mode === 'focused' && isPrimary(node))
+        const framed =
+          view.mode === 'full' ||
+          (view.mode === 'focused' && isPrimary(node)) ||
+          (framesTerminal && holdsTerminal(node))
         if (framed && !isGroupTask(node)) {
           if (streamsLive(node)) {
             if (streamMidLine) {
@@ -713,6 +729,14 @@ export function defaultLogger(
         refresh(true)
       }
       if (isGroupTask(node)) return
+      if (holdsTerminal(node) && streamsLive(node) && outcome.status !== 'skipped') {
+        if (streamMidLine) {
+          writer.write('\n')
+          streamMidLine = false
+        }
+        emitFrameClose(formatFrameClose(node, outcome, colors))
+        return
+      }
       const isHit = isCacheHit(outcome.status)
       switch (view.mode) {
         case 'none':

package/src/orchestrator/options.ts

@@ -70,6 +70,12 @@ export interface RunOptions {
    * saying it is not.
    */
   remoteRequested?: boolean
+  /**
+   * The `cacheScope` a run takes when `vx.workspace` names none. The CLI
+   * passes `'read-only'` off CI (`CI` unset, `0` or `false`) unless
+   * `--cache` names the remote; omitted → trusted.
+   */
+  defaultCacheScope?: string
   /**
    * CI mode: load configs FROM the committed vx-lock.json instead of
    * evaluating them (frozen-env reproducibility). Requires the lock
@@ -189,6 +195,12 @@ export interface RunOptions {
    * is replaced only when the next cycle starts.
    */
   holdPersistent?: boolean
+  /**
+   * vx's stdin is a terminal: each `exec.interactive` task is handed it,
+   * alone (placement.ts `terminalHolders`). The CLI sets it from
+   * `isatty(0)`; absent, an interactive task runs as any task.
+   */
+  tty?: boolean
   log?: Logger
   /**
    * Inject the run's event bus. When provided, the orchestrator emits

package/src/orchestrator/placement.ts

@@ -2,12 +2,13 @@
 // executors, and the plan-mode view of it. Split from run.ts on 2026-09-10
 // (pure motion). A task is pinned to this machine when it is persistent,
 // depends on a persistent task, is sandboxed, says `exec.remote: false`, or
-// folds a runtime probe into its key;
+// folds a runtime probe into its key; an `exec.interactive` task goes to the
+// local floor directly, as only it can hand over this terminal;
 // everything else asks the executors in declaration order, and the local
 // floor takes what nothing claimed.
 
-import { machineParallelism } from '../util/index.js'
-import { selectExecutor, type TaskExecutor } from '../exec/index.js'
+import { machineParallelism, UserError } from '../util/index.js'
+import { isLocalExecutor, selectExecutor, type TaskExecutor } from '../exec/index.js'
 import { isGroupTask, type TaskNode } from '../graph/index.js'
 import { resolveDownloadModes } from './download-policy.js'
 import type { Logger } from './logger.js'
@@ -75,6 +76,49 @@ function withProbedRuntime(nodes: Map<string, TaskNode>, pinned: Set<string>): S
   return pinned
 }
 
+/**
+ * The tasks that hold the terminal in a run on one: every
+ * `exec.interactive` task when vx's stdin is a TTY, none otherwise. A
+ * persistent one holds it until the run ends, so a run may have one, and
+ * every other interactive task must run before it (a dependency); anything
+ * else would have two tasks reading the same keys. Refused before any task
+ * runs.
+ */
+export function terminalHolders(nodes: Map<string, TaskNode>, tty: boolean): Set<string> {
+  const holders = new Set<string>()
+  if (!tty) return holders
+  for (const node of nodes.values()) {
+    if (node.config.exec?.interactive === true) holders.add(node.id)
+  }
+  const servers = [...holders].filter((id) => nodes.get(id)!.config.exec!.persistent !== undefined)
+  if (servers.length > 1) {
+    throw new UserError(
+      `${servers.join(' and ')} are persistent and interactive: a server holds the terminal ` +
+        `until the run ends, so one run can hold one — run them in separate terminals`,
+    )
+  }
+  if (servers.length === 0) return holders
+  const server = servers[0]!
+  const before = new Set<string>()
+  const stack = [...nodes.get(server)!.deps]
+  while (stack.length > 0) {
+    const id = stack.pop()!
+    if (before.has(id)) continue
+    before.add(id)
+    stack.push(...nodes.get(id)!.deps)
+  }
+  const clash = [...holders].filter((id) => id !== server && !before.has(id))
+  if (clash.length > 0) {
+    throw new UserError(
+      `${server} is persistent and interactive, so it holds the terminal until the run ends, ` +
+        `and ${clash.join(', ')} would ask for it too: make ${server} depend on ` +
+        `${clash.length === 1 ? 'it' : 'them'}, or run ${clash.length === 1 ? 'it' : 'them'} on ` +
+        `${clash.length === 1 ? 'its' : 'their'} own`,
+    )
+  }
+  return holders
+}
+
 export interface Placements {
   executors: Map<string, TaskExecutor>
   /**
@@ -118,8 +162,14 @@ export function placeTasks(
     remoteOnlyNoop: new Set(),
     remoteOnly: new Set(),
   }
+  // `resolveExecutors` puts it last in every list.
+  const floor = executors.find(isLocalExecutor)!
   for (const node of nodes.values()) {
     if (isGroupTask(node) || node.config.exec?.persistent !== undefined) continue
+    if (node.config.exec?.interactive === true) {
+      placements.executors.set(node.id, floor)
+      continue
+    }
     const executor = selectExecutor(
       executors,
       {

package/src/orchestrator/prepare.ts

@@ -16,6 +16,7 @@ import {
   type CacheLayer,
   type CachePolicy,
   FULL_CACHE_POLICY,
+  scopeCachePolicy,
   GitFilesCache,
   LayeredCache,
   applyGitEnumeration,
@@ -29,6 +30,8 @@ import {
   computeNestedProjectDirs,
   computeWorkspaceFingerprints,
   findWorkspaceRoot,
+  cacheScopeEnvError,
+  isCacheScope,
   type LoadReads,
   loadWorkspace,
   FROZEN_WITHOUT_LOCK,
@@ -90,6 +93,8 @@ export interface PreparedRun {
    * would be saved still cleans its outputs before executing.
    */
   hasRemoteLayer: boolean
+  /** `--cache` with the workspace's `cacheScope` applied: what the layers were built under. */
+  cachePolicy: CachePolicy
   /**
    * Scheduling priorities from plugins' `schedule` stage (task id → weight,
    * merged over the structural baseline by the scheduler). Empty when no
@@ -257,7 +262,14 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
 
   // The local cache opens BEFORE the configs load: it is also where their
   // cached evaluations live.
-  const policy: CachePolicy = options.cache ?? FULL_CACHE_POLICY
+  // `VX_CACHE_SCOPE` wins over the workspace (and `github()`'s guess):
+  // a CI job that knows its trust level says so without editing config.
+  const envScope = process.env['VX_CACHE_SCOPE'] || undefined
+  if (envScope !== undefined && !isCacheScope(envScope)) throw cacheScopeEnvError()
+  const policy: CachePolicy = scopeCachePolicy(
+    options.cache ?? FULL_CACHE_POLICY,
+    envScope ?? workspaceConfig?.cacheScope ?? options.defaultCacheScope,
+  )
   const localCache = new Cache(
     cacheDir,
     { read: policy.localRead, write: policy.localWrite },
@@ -455,6 +467,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
         cache,
         localCache,
         hasRemoteLayer,
+        cachePolicy: policy,
         priorities: new Map(),
         nodes: new Map(),
         keyOnly: new Map(),
@@ -610,6 +623,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       cache,
       localCache,
       hasRemoteLayer,
+      cachePolicy: policy,
       priorities,
       nodes,
       keyOnly,

package/src/orchestrator/run.ts

@@ -5,12 +5,7 @@
 import type { ProjectEntry } from '../workspace/index.js'
 import { loadWorkspace, unreachedHint, unreachedPackages } from '../workspace/index.js'
 import path from 'node:path'
-import {
-  type CacheLayer,
-  type CachePolicy,
-  FULL_CACHE_POLICY,
-  stopRuntimeProbes,
-} from '../cache/index.js'
+import { type CacheLayer, type CachePolicy, stopRuntimeProbes } from '../cache/index.js'
 import { VERSION } from '../version.js'
 import {
   resetSandbox,
@@ -77,6 +72,7 @@ import {
   placeTasks,
   planExecutorOf,
   poolOfPlacement,
+  terminalHolders,
   UNPLACED_EXECUTOR,
   locallyPlaced,
 } from './placement.js'
@@ -300,7 +296,10 @@ export async function run(options: RunOptions): Promise<RunSummary> {
   // See docs/design/event-stream-2026-06.md.
   const terminal =
     options.log === undefined
-      ? defaultLogger(colors, resolveOutputView(options), process.stdout, { coalesce: true })
+      ? defaultLogger(colors, resolveOutputView(options), process.stdout, {
+          coalesce: true,
+          ...(options.tty === true ? { tty: true } : {}),
+        })
       : null
   const sink = options.log ?? terminal!
   // An injected bus already has surfaces subscribed; we add the terminal
@@ -471,6 +470,7 @@ async function runOnBus(
   // worker slot. Group tasks run nothing; persistent tasks never reach an
   // executor (local by construction) — both stay off the map.
   const placements = await abandoning(() => placeTasks(nodes, executors))
+  const holders = await abandoning(() => terminalHolders(nodes, options.tty === true))
   // A `remote: 'only'` task nobody takes succeeds WITHOUT running. That is
   // deliberate — on a machine with no remote pool the ambient state already
   // is what the task would have produced — but it must not be SILENT: a task
@@ -673,10 +673,7 @@ async function runOnBus(
     // actually governed the run. Reading the raw request here made tasks
     // clean their outputs before every exec for a save that never
     // happened.
-    const policy: CachePolicy = effectiveCachePolicy(
-      options.cache ?? FULL_CACHE_POLICY,
-      prepared.hasRemoteLayer,
-    )
+    const policy: CachePolicy = effectiveCachePolicy(prepared.cachePolicy, prepared.hasRemoteLayer)
     if (options.remoteRequested === true && !prepared.hasRemoteLayer) {
       log.status(
         'vx: --cache named the remote cache, but no cache plugin in vx.workspace.* supplies one — the remote axes are off for this run',
@@ -942,6 +939,7 @@ async function runOnBus(
         ...(upfrontKey !== undefined ? { upfrontKey } : {}),
         ...(tainted ? { taintedUpstream: true } : {}),
         ...(dependedOn.has(node.id) ? {} : { noDependants: true as const }),
+        ...(holders.has(node.id) ? { terminal: true as const } : {}),
         fingerprintWatch,
         ...(sandboxArmer !== null ? { armSandbox: () => sandboxArmer.arm() } : {}),
         keyedProjects: keyed,
@@ -975,6 +973,7 @@ async function runOnBus(
       settledOf: (o) => deferredSaves.get(o.node.id),
       ...(hasPooledExecutor(executors) ? { poolOf: poolOfPlacement(placements) } : {}),
       ...(admit !== undefined ? { admit } : {}),
+      ...(holders.size > 0 ? { exclusive: holders } : {}),
       ...(options.continueMode !== undefined ? { continueMode: options.continueMode } : {}),
       serverDied,
       signal: stopRun.signal,
@@ -1452,10 +1451,7 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
       workspaceRoot: prepared.workspaceRoot,
       workspaceFingerprint: prepared.workspaceFingerprint,
       cache: prepared.cache,
-      cachePolicy: effectiveCachePolicy(
-        options.cache ?? FULL_CACHE_POLICY,
-        prepared.hasRemoteLayer,
-      ),
+      cachePolicy: effectiveCachePolicy(prepared.cachePolicy, prepared.hasRemoteLayer),
       forwardArgs: options.forwardArgs,
       nestedDirsByProject: prepared.nestedDirsByProject,
       gitFilesCache: prepared.gitFilesCache,

package/src/workspace/config-schema.ts

@@ -30,12 +30,26 @@ import { nonJsonMessage, nonJsonPaths } from './json-data.js'
 // the same reason the task levels reject them: `plugin: [...]` (singular)
 // declared no plugins and ran the workspace bare, `cacheDirectory` left the
 // cache where it was — a config that loads and quietly does nothing it says.
+const CACHE_SCOPE_RULE =
+  "must be 'trusted', 'read-only', or a scope name of letters, digits and . _ - / @ (at most 128), like 'pr-123'"
+
+/** `cacheScope`'s rule, shared with `VX_CACHE_SCOPE`. */
+export function isCacheScope(v: unknown): v is string {
+  return typeof v === 'string' && /^[\w.@/-]{1,128}$/.test(v)
+}
+
+/** Why `VX_CACHE_SCOPE` is refused, in `cacheScope`'s words. */
+export function cacheScopeEnvError(): UserError {
+  return new UserError(`VX_CACHE_SCOPE ${CACHE_SCOPE_RULE}`)
+}
+
 const WORKSPACE_FIELDS = new Set([
   'concurrency',
   'cacheDir',
   'timeout',
   'cacheRetention',
   'affectedBase',
+  'cacheScope',
   'plugins',
 ])
 
@@ -112,6 +126,9 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
       throw new UserError(`${configPath}: \`affectedBase\` must be a git ref like 'origin/main'`)
     }
   }
+  if (config.cacheScope !== undefined && !isCacheScope(config.cacheScope)) {
+    throw new UserError(`${configPath}: \`cacheScope\` ${CACHE_SCOPE_RULE}`)
+  }
   if (config.plugins !== undefined) {
     if (!Array.isArray(config.plugins)) {
       throw new UserError(`${configPath}: \`plugins\` must be an array of plugin objects`)
@@ -400,6 +417,34 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
           }
         }
       }
+      const interactive = (exec as { interactive?: unknown }).interactive
+      if (interactive !== undefined && typeof interactive !== 'boolean') {
+        throw new UserError(`${where}.exec.interactive must be a boolean (or omitted)`)
+      }
+      if (interactive === true) {
+        if (cache !== undefined) {
+          throw new UserError(
+            `${where}: \`cache\` is not allowed on an interactive task — what it does ` +
+              `depends on what is typed, which no key holds`,
+          )
+        }
+        // bwrap's --new-session keeps the terminal usable (probed), but the
+        // sandboxed spawn pipes the task's streams: its stderr is read for
+        // the tracer's own errors (sandbox-runtime.ts).
+        if ((exec as { sandbox?: unknown }).sandbox !== undefined) {
+          throw new UserError(
+            `${where}: \`sandbox\` is not allowed on an interactive task — a sandboxed ` +
+              `task's output passes through vx, and an interactive one writes to the terminal`,
+          )
+        }
+        const ready = (exec as { persistent?: { readyWhen?: unknown } }).persistent
+        if (typeof ready === 'object' && ready !== null && ready.readyWhen !== undefined) {
+          throw new UserError(
+            `${where}: \`persistent.readyWhen\` is not allowed on an interactive task — ` +
+              `its output goes to the terminal, so vx reads none of it; it is ready once spawned`,
+          )
+        }
+      }
       const persistent = (exec as { persistent?: unknown }).persistent
       if (persistent !== undefined) {
         if (typeof persistent !== 'object' || persistent === null) {
@@ -691,6 +736,7 @@ const EXEC_FIELDS = new Set([
   'timeout',
   'retries',
   'persistent',
+  'interactive',
   'remote',
   'sandbox',
 ])
@@ -767,8 +813,7 @@ const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, s
       outputLogs: 'the `--output-logs` flag of `vx run`',
       // Turbo's `interactive` / `with`, Nx's `cwd` / `parallelism` /
       // `configurations`: refused with no word on where they went (D-89).
-      interactive:
-        'a command run outside vx: a task never reads the terminal (its stdin is EOF, or a pipe vx holds under `exec.persistent`)',
+      interactive: '`exec.interactive: true`',
       with: '`dependsOn` on each task it runs beside: a persistent one stays up, and this task starts once it is ready',
       cwd: '`cd <dir> && …` in `exec.command`: a task runs in its project directory',
       parallelism:
@@ -789,8 +834,6 @@ const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, s
       commands: 'one `command` (`a && b`, or `a & b; wait` to run them at once), or one task each',
       parallel: 'one task each, which vx runs at once, or `a & b; wait` in `command`',
       shell: 'no field: `command` always runs in a shell',
-      interactive:
-        'a command run outside vx: a task never reads the terminal (its stdin is EOF, or a pipe vx holds under `persistent`)',
     },
   ],
   // wireit's `files` / `output` and include-style spellings written into

package/src/workspace/index.ts

@@ -34,7 +34,12 @@ export {
   loadWorkspaceConfig,
   WORKSPACE_CONFIG_FILENAMES,
 } from './project-loader.js'
-export { validateProjectConfig, validateWorkspace } from './config-schema.js'
+export {
+  cacheScopeEnvError,
+  isCacheScope,
+  validateProjectConfig,
+  validateWorkspace,
+} from './config-schema.js'
 export type { LoadProjectConfigOptions } from './project-loader.js'
 export {
   blobOidOf,